Skip to main content

Routing API

|



The Routing API is a powerful navigation service that computes optimal routes between two or more locations, delivering comprehensive route planning capabilities for a wide range of applications. Whether you're building a logistics platform, a delivery management system, a navigation app, or an electric vehicle route planner, this API provides the flexibility and precision needed to create intelligent routing solutions.

The API goes beyond simple point-to-point routing by offering advanced features such as multi-waypoint routes, vehicle-specific constraints, real-time traffic avoidance, and specialized support for electric vehicles with charging station integration. With support for multiple transport modes (car, truck, bike, pedestrian, and public transport), customizable route preferences (fastest, shortest, economic, scenic), and detailed route attributes including elevation profiles and road surface data, you can tailor routing calculations to match your exact requirements.

Key capabilities include turn-by-turn navigation instructions with street names, alternative route options, route sections with speed limits and road classifications, and the ability to specify custom waypoints to control the route path. The API also supports comprehensive vehicle specifications including physical dimensions, weight restrictions, and fuel/battery properties, making it ideal for commercial fleet management and specialized vehicle routing scenarios.

Complete API Reference

View the complete Routing API Reference for detailed request/response schemas, examples, and interactive documentation.

Endpoint: POST /routing

Base URL: https://api.magiclane.net/api/v1

Key Features​

  • Find the most optimal route and estimated time of arrival (ETA) between origin and destination
  • Get turn-by-turn directions for different transport modes including car, truck, bike, and pedestrian
  • Calculate routes based on vehicle specifications such as dimensions, weight, and fuel type
  • Add custom waypoints to follow a specific path geometry instead of the automatically calculated optimal route
  • Support for multiple route types: fastest, shortest, economic, and scenic
  • Electric vehicle routing with charging station integration
  • Detailed route information including distance, time, elevation profiles, and road surface data
  • Comprehensive turn-by-turn instructions with street names
  • Route sections with speed limits, country codes, and road classifications
  • Roundtrip route generation from a single location with customizable range

Required Parameters​

  • waypoints - Array of coordinates [[longitude, latitude], ...]

Optional Parameters​

  • transport - Route transport mode (car, lorry, truck, pedestrian, bike, public)
  • type - Route type (fastest, shortest, economic, scenic) - see Common Parameters
  • avoid - Features to avoid (highway, toll, ferry, unpaved, turnaround, traffic, roadblocks, immutable_roadblocks) - see Common Parameters
  • vehicle - Detailed vehicle specifications including mass, dimensions, fuel type, battery capacity - see Common Parameters
  • details - Level of detail in response (full, path, timedistance)
  • alternatives - Number of alternative routes to return
  • locale - ISO 3166-1 language code for instructions
  • terrain - Include elevation profile data
  • track - Custom path geometry to follow
  • geometry - Path encoding method (lineString, polyline)
  • fitness - Fitness factor [0,1] for tuning bike/pedestrian routing
  • emergency - Enable emergency vehicle mode (access emergency-only roads, ignore turn restrictions)
  • departure_time - Departure time as EPOCH timestamp
  • accurate_approach - Approach intermediates and destination according to region drive side
  • pt - Public transit parameters (algo_type, sorting, transfer times, walk distance)
  • sections - Route sections to include in response (surface, road_class, speed_limit, country)
  • avoid_geofence_areas - Array of geofence area tags/names to avoid
  • avoid_geofence_anti_areas - Array of geofence anti-area tags/names to avoid
  • roundtrip - Roundtrip parameters (range, random seed)
  • debug - Beautify output for easy human readability

Example Request - Car routing with avoidances and alternatives​

curl -X POST https://api.magiclane.net/api/v1/routing \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transport": "car",
    "type": "fastest",
    "waypoints": [[13.388860, 52.517037], [13.397634, 52.529407]],
    "avoid": ["toll", "highway"],
    "details": "full",
    "alternatives": 2,
    "locale": "en"
  }'

This example demonstrates a basic car routing request between two points in Berlin. It requests the fastest route while avoiding toll roads and highway segments — a common preference for local urban navigation or cost-conscious drivers. The details: "full" parameter returns complete turn-by-turn instructions with street names, and alternatives: 2 asks the API to return up to 2 alternative routes alongside the primary one, letting the user choose based on distance or time tradeoffs. The locale: "en" ensures all navigation instructions are returned in English.

Example Request - Truck Route with Dimensional Restrictions​

curl -X POST https://api.magiclane.net/api/v1/routing \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transport": "truck",
    "type": "fastest",
    "waypoints": [
      [4.2899, 51.9225],
      [6.7735, 51.2277],
      [8.6821, 50.1109]
    ],
    "details": "full",
    "geometry": "lineString",
    "locale": "en",
    "vehicle": {
      "mass": 32000,
      "speed": 22.22,
      "fuel": "diesel",
      "height": 400,
      "length": 1650,
      "width": 255,
      "axle": 11500
    },
    "avoid": ["toll", "ferry"],
    "sections": ["country", "speed_limit"],
    "alternatives": 1,
    "accurate_approach": true,
    "debug": true
  }'

This is a standard use case for freight management platforms and TMS (Transport Management Systems). The intermediate waypoint in Düsseldorf forces a pickup stop. Vehicle dimensions ensure the route avoids roads with height/weight restrictions, and sections: ["country"] helps track border crossings for regulatory compliance (tolling, driver rest rules per country).

Example Request - Bike Route with Terrain and Fitness Profile​

curl -X POST https://api.magiclane.net/api/v1/routing \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transport": "bike",
    "type": "fastest",
    "waypoints": [
      [2.3522, 48.8566],
      [2.2945, 48.8584],
      [2.2770, 48.8606]
    ],
    "details": "full",
    "geometry": "polyline",
    "locale": "fr",
    "terrain": true,
    "fitness": 0.6,
    "vehicle": {
      "profile": "city"
    },
    "avoid": ["unpaved"],
    "sections": ["surface", "road_class"],
    "alternatives": 2,
    "debug": true
  }'

This is a typical use case for cycling navigation and fitness apps (like bike commute planners or tour guides). The fitness factor adjusts the route to the rider's ability level, terrain: true returns elevation data for climb visualization, profile: "city" optimizes for urban cycling, and sections: ["surface", "road_class"] lets the app display road quality along the route — helping riders avoid rough or single-track segments.

Example Request - Roundtrip Route from a Single Location​

curl -X POST https://api.magiclane.net/api/v1/routing \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transport": "bike",
    "type": "shortest",
    "waypoints": [[11.5820, 48.1351]],
    "details": "full",
    "geometry": "polyline",
    "locale": "en",
    "terrain": true,
    "fitness": 0.7,
    "vehicle": {
      "profile": "road"
    },
    "roundtrip": {
      "range": 15000,
      "random": 42
    },
    "sections": ["surface"],
    "debug": true
  }'

This generates a circular route starting and ending at the same point (central Munich), with a target distance of ~15 km. The random seed produces a different loop each time it's changed — useful for apps offering "surprise me" variety in training routes. Combined with terrain and sections: ["surface"], it's ideal for fitness apps that want to show elevation profiles and surface quality for the generated loop.

Example Request - Bike Route on Track​

curl -X POST https://api.magiclane.net/api/v1/routing \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transport": "bike",
    "type": "fastest",
    "waypoints": [
      [2.24559, 48.88562],
      [2.2767, 48.77927]
    ],
    "avoid": ["unpaved"],
    "details": "path",
    "profile": "city",
    "fitness": 0.8,
    "debug": true,
    "geometry": "polyline",
    "locale": "fr",
    "track": {
      "waypoint_index": 1,
      "coords": [
        [2.24388, 48.88392],
        [2.24388, 48.88392],
        [2.24388, 48.88392],
        [2.24346, 48.8839],
        [2.24304, 48.88387],
        [2.24261, 48.88385],
        [2.24135, 48.88378],
        [2.24009, 48.88371],
        [2.24009, 48.88371],
        [2.23882, 48.88363],
        [2.23756, 48.88356],
        [2.23419, 48.88337],
        [2.23124, 48.8832],
        [2.22955, 48.88311],
        [2.22786, 48.88301],
        [2.22618, 48.88292],
        [2.22491, 48.88285],
        [2.22491, 48.88285],
        [2.22281, 48.88273],
        [2.22112, 48.88263],
        [2.21986, 48.88256],
        [2.21817, 48.88246],
        [2.21648, 48.88237],
        [2.21522, 48.8823],
        [2.21396, 48.88222],
        [2.21269, 48.88215],
        [2.21185, 48.8821],
        [2.21055, 48.88231],
        [2.21055, 48.88231],
        [2.20886, 48.88221],
        [2.20675, 48.88209]
      ]
    }
  }'

This example demonstrates bike routing that follows a predefined track geometry in the Paris area. The track parameter constrains the route to snap to the provided coordinate sequence near waypoint index 1, overriding the automatically calculated optimal path for that segment. This is useful for guided cycling tours, GPX track playback, or apps where users record and replay a specific route. The fitness: 0.8 value targets a moderately fit rider, avoid: ["unpaved"] keeps the route on paved surfaces, and details: "path" returns the route geometry without full turn-by-turn instructions — suitable when only the path shape is needed.

Example Request - Time and Distance Only​

curl -X POST https://api.magiclane.net/api/v1/routing \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transport": "car",
    "type": "fastest",
    "waypoints": [[13.388860, 52.517037], [13.397634, 52.529407]],
    "details": "timedistance"
  }'

Using details: "timedistance" returns only the total route distance and time, omitting geometry, instructions, and section data. This is the most lightweight response option — ideal for ETA calculations, distance matrix lookups, or any scenario where only the cost of a route is needed rather than its full path.

Example Request - Public Transport Routing​

curl -X POST https://api.magiclane.net/api/v1/routing \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transport": "public",
    "type": "fastest",
    "waypoints": [[13.3690, 52.5251], [13.4345, 52.5106]],
    "details": "full",
    "geometry": "lineString",
    "locale": "en",
    "departure_time": 1744012800,
    "alternatives": 3,
    "pt": {
      "algo_type": "departure_based",
      "sorting": "least_transfers",
      "minimum_transfer_time": 2,
      "maximum_transfer_time": 30,
      "maximum_walk_distance": 500
    }
  }'

This example routes a traveler from Berlin Hauptbahnhof to Berlin Ostbahnhof via public transit. The pt.algo_type: "departure_based" setting interprets departure_time as the earliest departure time, and pt.sorting: "least_transfers" ranks results to minimize the number of connections — ideal for passengers who prefer fewer changes over the absolute fastest route. A minimum_transfer_time of 2 minutes excludes unrealistically tight connections, maximum_transfer_time of 30 minutes caps wait time between legs, and maximum_walk_distance of 500 meters limits how far the traveler must walk between transit stops. Requesting 3 alternatives gives the user a range of journeys to compare.

Response Structure​

The API returns a JSON object containing:

  • info - Copyright and attribution information
    • copyrights - Array of copyright holder strings
  • routes - Array of route objects, each containing:
    • distance - Total route distance in meters
    • time - Total route time in seconds
    • bbox - Bounding box coordinates [east, south, west, north]
    • points - Route path coordinates
      • type - Encoding type ("lineString" or "polyline")
      • coords - Array of coordinate arrays [[lon, lat, alt], ...] (when type is "lineString")
      • polyline - Google polyline encoded string (when type is "polyline")
    • instructions - Array of turn-by-turn navigation instruction objects
      • id - Turn event identifier
      • distance - Distance in meters from route start
      • time - Time in seconds from route start
      • point - Index in the path coordinates list
      • heading - Turn heading in degrees
      • turn - Turn instruction text (translated to the requested locale)
      • follow - Follow-the-road instruction text (translated to the requested locale)
      • street - Array of street names at the turn exit
      • roundabout_exit - Roundabout exit number (present only for roundabout instructions)
    • sections - Array of road detail section objects
      • surface - Array of road surface sections
        • type - Surface type (e.g., "smooth")
        • start_point - Start index in path coordinates list
        • end_point - End index in path coordinates list
        • start_distance - Start distance in meters from route start
        • end_distance - End distance in meters from route start
      • road_info - Array of road class sections
        • type - Road class type
        • start_point - Start index in path coordinates list
        • end_point - End index in path coordinates list
        • start_distance - Start distance in meters from route start
        • end_distance - End distance in meters from route start
      • speed_limit - Array of speed limit sections
        • speed - Speed limit value
        • start_point - Start index in path coordinates list
        • end_point - End index in path coordinates list
        • start_distance - Start distance in meters from route start
        • end_distance - End distance in meters from route start
      • country - Array of country sections
        • iso - Country ISO 3166-1 alpha-3 code
        • start_point - Start index in path coordinates list
        • end_point - End index in path coordinates list
        • start_distance - Start distance in meters from route start
        • end_distance - End distance in meters from route start
    • terrain - Elevation profile data (if requested)
      • elevations - Array of altitude values in meters above sea level, at 30 m resolution
      • total_up - Total uphill elevation gain in meters
      • total_down - Total downhill elevation loss in meters
      • climb_sections - Array of climb section objects
        • start - Start distance in meters from route start
        • end - End distance in meters from route start
        • slope - Average climbing slope for the section
        • grade - Climbing difficulty level

For information about common parameters shared across multiple APIs, including vehicle specifications, route types, and avoidance options, see Common Parameters.

For information about calculating reachable areas from a given location, see Isochrones API.

Last updated on