Skip to main content
Guides

Routing

Estimated reading time: 30 minutes

In this guide you will learn how to request navigation instructions for a route, as well as statistics about the route.

Setup​

First, get an API key token, see the Getting Started guide.

Routing entry point​

URL: https://routes.magiclaneapis.com/v1

EXAMPLE​

These are complete working examples in several different languages, showing how to use the REST API routing. You can try them right now.

Linux terminal / Windows command prompt:

curl "https://routes.magiclaneapis.com/v1" -X POST -H "Content-Type: application/json" -H "Authorization: YOUR_API_KEY_TOKEN" -d @payload.json

Linux note - do not use @~/payload.json instead of @/home/user/payload.json because ~ does not resolve due to the @ ; use only relative path @payload.json or absolute path @/home/user/payload.json

where

payload.json is a text file containing the following:

complete minimal payload.json file - 2 waypoints, the first for departure and the second for destination:

{
  "transport": "bike",
  "waypoints": [[2.24559,48.88562],[2.27670,48.77927]],
  "avoid": ["unpaved","highway"],
  "debug": true
}

complete payload.json file - 2 waypoints, the first for departure and the second for destination; all default values shown explicitly - this json is equivalent to, and produces the same output as, the previous json above; no intermediate track version:

{
  "transport": "bike",
  "type": "fastest",
  "waypoints": [[2.24559,48.88562],[2.27670,48.77927]],
  "avoid": ["unpaved","highway"],
  "details": "full",
  "alternatives": 0,
  "profile": "city",
  "terrain": false,
  "hillskip": 0.5,
  "emergency": false,
  "debug": true,
  "locale": "en"
}

Complete json request (json payload) - version with sample track included - 2 waypoints, the first for departure and the second for destination; additionally, track coordinates are given for matching a route between the departure and destination along the specified track if possible:

{
    "transport": "bike",
    "type": "fastest",
    "waypoints": [[2.24559,48.88562],[2.27670,48.77927]],
    "avoid": ["unpaved","highway"],
    "details": "full",
    "alternatives": 2,
    "profile": "city",
    "terrain": false,
    "hillskip": 0.8,
    "emergency": false,
    "debug": true,
    "locale": "fr",
    "track":
    {
             "accurate": false,
             "restrictions": false,
             "waypoint_index": 1,
             "coords": [
                     [2.24388, 48.88392, 0.00000],
                     [2.24388, 48.88392, 0.00000],
                     [2.24388, 48.88392, 0.00000],
                     [2.24346, 48.88390, 0.00000],
                     [2.24304, 48.88387, 0.00000],
                     [2.24261, 48.88385, 0.00000],
                     [2.24135, 48.88378, 0.00000],
                     [2.24009, 48.88371, 0.00000],
                     [2.24009, 48.88371, 0.00000],
                     [2.23882, 48.88363, 0.00000],
                     [2.23756, 48.88356, 0.00000],
                     [2.23419, 48.88337, 0.00000],
                     [2.23124, 48.88320, 0.00000],
                     [2.22955, 48.88311, 0.00000],
                     [2.22786, 48.88301, 0.00000],
                     [2.22618, 48.88292, 0.00000],
                     [2.22491, 48.88285, 0.00000],
                     [2.22491, 48.88285, 0.00000],
                     [2.22281, 48.88273, 0.00000],
                     [2.22112, 48.88263, 0.00000],
                     [2.21986, 48.88256, 0.00000],
                     [2.21817, 48.88246, 0.00000],
                     [2.21648, 48.88237, 0.00000],
                     [2.21522, 48.88230, 0.00000],
                     [2.21396, 48.88222, 0.00000],
                     [2.21269, 48.88215, 0.00000],
                     [2.21185, 48.88210, 0.00000],
                     [2.21055, 48.88231, 0.00000],
                     [2.21055, 48.88231, 0.00000],
                     [2.20886, 48.88221, 0.00000],
                     [2.20675, 48.88209, 0.00000]
             ]
          }
}

Note that the waypoints list contains the minimum required number of 2 coordinates, one for the departure position and one for the destination, therefore, their 0-based indexes are 0 and 1, respectively. In the track structure, the waypoint_index (insertion index) parameter is set to 1, which means that the track coordinates are inserted in the primary waypoints list starting at index 1. Thus, in the above example, the departure waypoint is at index 0, followed by the track waypoints at indexes 1-31, followed by the destination waypoint at index 32.

In a linux terminal you can also send the request directly from the command line, without a file, like this: (this method does not work on windows)

curl "https://routes.magiclaneapis.com/v1" -X POST -H "Content-Type: application/json" -H "Authorization: YOUR_API_KEY_TOKEN" -d \
'{
...
}'

The only difference is the added backslash after -d, and then the filename @/home/user/payload.json is replaced with the contents of the json file, starting with the next line - note that a single quote ‘ is added before the leading curly brace { and after the trailing curly brace } to enclose the file contents in single quotes - no backslashes are needed between the single quotes.

REQUEST PARAMETER DEFINITIONS​

Request body schema: application/json

keyvalue
transportSpecify the transportation mode to be used on the route.
Type: string
Default value: "car"
Default value: "car"
typeSpecify the route evaluation type.
Type: string
Default value: "fastest"
Possible values: “fastest”, “shortest” (car/lorry), “economic” (bike)
waypoints
(mandatory
parameter)		The route waypoints specified in visit order
Type: array of coords in format [[lon, lat]]
This parameter is mandatory. There must be at least 2 waypoints - the first waypoint is the departure position and the last waypoint is the destination
avoidThe routing avoidance - what to avoid along the route
Type: string array
Default value: empty
Possible values: “highway”, “ferry”, “toll”, “unpaved”, “turnaround”, “traffic” (car/lorry), “roadblocks” (car/lorry)
detailsRoute result details
Type: string
Default value: "full"
Possible values: “full” - route path + instructions “path” - route path only “timedistance” - route time + distance
alternativesThe number of requested alternate routes to be computed, not including the main route result
Type: integer
Default value: 0
Internally the services will trim the requested alternatives to max 2 for car/lorry/bike/pedestrian, 10 for public (transport)
profileSpecify the route transport profile
Type: string
Default value: "city" for bike, "walk" for pedestrian
Possible values: “city”, “road”, “cross”, “mountain” (bike); “walk”, “hike” (pedestrian)
terrainInclude terrain information in the result
Type: bool
Default value: false
hillskipHill avoidance factor (bike only)
Type: float
Default value: 0.5
trackRoute over existing input track - options
Type: structure
track: { accurate }
(property within
track structure)		Apply accurate route match on map data for track points
Type: bool
Default value: true
Should be true when matching a GPS capture track
Should be false when matching a hand drawn track
track: { restrictions }
(property within
track structure)		Apply map restrictions when routing over track
Type: bool
Default value: trueif accurate == true, else false
track: { coords }
(property within
track structure)		List of 2 or more coordinates to include in route
Type: array of coords in format [[lon, lat, {alt}]]
Track coordinates in lon, lat, alt (optional). At least 2 track coordinate entries should be provided.
track: { waypoint_index }
(property within
track structure)		The track waypoint 0-based index in the route waypoints
Type: integer
Default value: track waypoint is added at end of route waypoints
Inserting the track in the route waypoints list so that the first track waypoint is at 0-based index 2:
[0]departure_waypoint, [1]first_waypoint, [2]track, waypoint_before_destination, [n]destination_waypoint
emergencyApply emergency profile to the route
Type: bool
Default value: false
Vehicle will be allowed on emergency tagged links, CDMs with emergency tag will be ignored, etc.
debugIf true, the JSON output is formatted for easy reading
Type: bool
Default value: false
localeThe ISO 639-1 language for the routing result
Type: string
Default value: en

RESPONSE​

MagicLane header

{
  "info": {
    "copyrights": [
      "MagicLane"
    ]
  },
  "routes": [
  {

Route summary

The distance in meters, the time in seconds, and the bounding box containing the entire route, given as two longitude,latitude coordinate pairs of the diagonally opposite corners of the rectangle containing the route, are given.

   "distance": 16552,
   "time": 3709,
   "bbox": [
     2.2274959375000000783,
     48.779269999999996799,
     2.2944959374999998047,
     48.885850625000003333
   ],

Route path points

The longitude,latitude coordinate pair of points along the route.

   "points": {
     "type": "LineString",
     "coordinates": [
       [
         2.2456190624999998739,
         48.885588437499997383
       ],
       [
         2.2459999999999999964,
         48.885763124999996876
       ],
       // ...
     ]
   },

Route instructions list

each instruction block contains:

id; distance from beginning of route; travel time from beginning of route; heading (direction) clockwise, where 0 is north, 90 is east, 180 is south, and 270 or -90 is west; turn instruction; follow instruction; street name(s);

   "instructions": [
   {
       "id": 22,
       "distance": 0,
       "time": 0,
       "heading": 55.10716878309646205,
       "turn": "",
       "follow": "Follow Rue Roque de Fillol for 50 m.",
       "street": [
         "Rue Roque de Fillol"
       ]
   },
   // ...
   ],

Terrain/topography elevation

elevation in meters above sealevel, at a 30 meter horizontal sample resolution;

"terrain": {
     "elevations": [
       38.69173431396484375,
       39.398284912109375,
       39.90000152587890625,
       // ...
       ],
     "total_up": 112.6616668701171875,
     "total_down": 42.85340118408203125

special climb sections

     "climb_sections": [
     {
       "start": 9360,
       "end": 12450,
       "slope": 6.2290167808532714844,
       "grade": 3
     }
     ]
   }

  }
 ]
}