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) - 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 route with Avoidance:

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.

Response Structure:

The API returns a JSON object containing:

info - Copyright and attribution information
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 as coordinate array or encoded polyline
- instructions - Turn-by-turn navigation instructions
- sections - Detailed road information (surface types, road classes, speed limits, countries)
- terrain - Elevation profile with uphill/downhill metrics (if requested)

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.

Related Documentation​

Related Documentation