Skip to main content

Routing API

Last updated: October 19, 2026 | 15 minutes read

Current version: 1.1.0 | View Release Notes

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.

:::info 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
  • Route sections with speed limits, country codes, and road classifications
  • Roundtrip route generation from a single location with customizable range
  • Comprehensive turn-by-turn text instructions with street names — the API returns text only; voice guidance, if required, must be generated client-side from the returned instructions

Required Parameters​

  • waypoints - Array of coordinates [[longitude, latitude], ...]. At least 2 are required, or 1 with roundtrip. A track counts as 2 (its start and end), so the waypoints can be omitted when a track is given; a track with accurate: false allows no waypoints

Optional Parameters​

  • transport - Route transport mode (car, lorry, truck, pedestrian, bike, public)
  • type - Route type (fastest, shortest, economic, scenic); the accepted values depend on the transport mode - 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
  • profile - Transport profile, a shortcut for vehicle.profile (send one or the other) - see Common Parameters
  • details - Level of detail in response (full, path, timedistance)
  • alternatives - Number of alternative routes to return after the main route. Default 0; at most 9 for public transport and 2 for the other transport modes. Alternatives are computed only when the route has exactly 2 waypoints, counting a track as 2 (its start and end)
  • locale - Language of the instructions: a lowercase ISO 639-1 code (e.g., en, de, fr) or an ISO 639-2 code (e.g., eng), optionally with a region (e.g., en-US). A code that cannot be parsed is rejected as invalid; a language without translations falls back to the closest available one. Default en
  • terrain - Include elevation profile data
  • track - Custom path geometry to follow (not allowed for public transport); track.waypoint_index sets its position among the waypoints, by default before the last one
  • geometry - Path encoding method (lineString, polyline)
  • fitness - Fitness factor [0,1] for tuning bike/pedestrian routing; values outside [0,1] are rejected as invalid
  • emergency - Enable emergency vehicle mode (access emergency-only roads, ignore turn restrictions)
  • departure_time - Departure time as a Unix timestamp in seconds; 0 or omitted means the current time. For public transport with pt.algo_type: "arrival_based" it is the arrival time, and an explicit value is interpreted as local time at the departure stop, the same as in the SDK
  • accurate_approach - Approach intermediates and destination according to region drive side
  • pt - Public transit parameters: algo_type (departure_based, arrival_based), sorting (best_time, least_walk, least_transfers), minimum_transfer_time (minutes, default 1), maximum_transfer_time (minutes, default 300), maximum_walk_distance (meters, default 5000)
  • 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"],
    "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"],
    "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",
    "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. No departure_time is given, so the journey starts at the current time. With pt.algo_type: "departure_based", a departure_time (Unix timestamp in seconds) would be the earliest departure time. pt.sorting: "least_transfers" ranks the results to minimize the number of connections, 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.

Each public transport route also carries a pt object with the ticket price (fare), the departure frequency and links to buy tickets (buy_ticket_urls) where this data is available for the operators used. Fare coverage depends on the region and operator; when a value is unknown, its key is left out.

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 (the main route followed by the alternatives), each containing:
    • distance - Total route distance in meters
    • time - Total route time in seconds
    • bbox - Bounding box [west, south, east, north] (min longitude, min latitude, max longitude, max latitude)
    • pt - Public transport information (only for transport: "public" routes, walk-only answers included)
      • fare - Total ticket price, one <amount> <currency> pair per currency (2 decimals, ISO 4217 code), separated by a space, e.g., "10.00 EUR"; the second-class fare where the operator has classes. Not returned when no fare data is available for the operators used
      • frequency - Seconds between consecutive departures of the same journey pattern, determined from the journeys found for this request. Not returned when it cannot be determined
      • respects_all_conditions - Currently always true, since the REST API accepts no wheelchair, bike or transit-type preferences
      • buy_ticket_urls - Array of links where tickets for this route can be bought. Not returned when none is known
    • segments - Array of route segments, one per part between two consecutive waypoints; public transport legs and EV charging stops also start a new segment (only with details: "full" and more than one segment)
      • distance - Segment distance in meters
      • time - Segment time in seconds
      • beginSoC / endSoC - Battery state of charge at the segment start / end, as a fraction of the battery capacity (electric vehicle and e-bike routes only)
      • chargeTime - Charging time in seconds at the charging station ending the segment (EV routes only, when not 0)
    • points - Route path (not returned for details: "timedistance")
      • type - Encoding type ("LineString" or "polyline")
      • coordinates - Array of coordinate arrays [[lon, lat, alt], ...] (when type is "LineString"). alt is the altitude in meters on points along the road network; points of an inaccurate track (accurate: false) and public transport shapes have no alt
      • polyline - Google polyline encoded string (when type is "polyline")
    • instructions - Array of turn-by-turn navigation instruction objects (only with details: "full")
      • id - Turn event identifier
      • distance - Distance in meters from the previous instruction to this one (0 for the first instruction)
      • time - Time in seconds from the previous instruction to this one (0 for the first instruction)
      • 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 on the instruction entering a roundabout)
      • beginSoC / endSoC - Battery state of charge at this / the next instruction, as a fraction of the battery capacity (electric vehicle and e-bike routes only)
      • chargeTime - Charging time in seconds, on the instruction entering a charging station (EV routes only, when not 0)
    • sections - Object with one array per section type requested in sections
      • surface - Array of road surface sections
        • type - Surface type (smooth, paved, rough, compacted, dirt, gravel, path, ice, snow, undefined)
        • 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_class - Array of road class sections
        • type - Road class type (motorway, state_road, road, street, cycleway, path, singletrack)
        • 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 in m/s (0 when unknown)
        • 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; not returned for public transport or details: "timedistance")
      • 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, in percent
        • grade - Climb category: 0 = HC (hardest), then 1 to 4, with 4 the easiest
  • error - Returned instead of routes when the request is invalid (HTTP 400) or no route can be computed (HTTP 200)
    • code - Numeric error code, for support and diagnostics; use reason and details for display
    • reason - Short error explanation, e.g., "Invalid input", "No routes available between these locations"; may be empty for some errors
    • details - What was wrong with the request (invalid requests only)

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