Routing

Stadia Maps provides turn-by-turn navigation, powered by the open-source Valhalla engine. Let's get started with the basics.

Basics

As with other types of requests, each routing request, if not made from JavaScript on your website, must be accompanied by an API key. You can include this either in your query string, or in a header as described here.

NOTE: In addition to your plan daily limits, we also impose rate limits that scale with your subscription to prevent abuse.

Tier Limit
Free 1/sec
Starter 3/sec
Standard 28/sec
Ultimate 115/sec

Routing mode (costing)

The Valhalla engine is flexible, and can give you different types of directions. The most common types are automobile and pedestrian. Valhalla refers to this as costing.

Waypoint specification

Waypoints must be specified in a locations list. You can either specify this as a query string argument named json containing a JSON object, or by including a JSON request body.

Your route can include multiple waypoints. You must include at least two waypoints. If a location is intended to be a through point on the journey, give it type through, otherwise use break.

Python example

Here is a simple python function that will try to fetch directions between two points.

import requests

def get_route_between_points(start_lat, start_lon, end_lat, end_lon, costing='auto'):
    params = {
        'api_key': ROUTING_API_KEY,
    }

    body = {
        'locations': [
            {
                'lat': start_lat,
                'lon': start_lon,
                'type': 'break'
            },
            {
                'lat': end_lat,
                'lon': end_lon,
                'type': 'break'
            }
        ],
        'costing': costing,
    }

    r = requests.get('https://route.stadiamaps.com/route', params=params, json=body)

    if r.status_code == 200:
        return r.json()
    else:
        return None

Sample output

{
  "trip": {
    "language": "en-US",
    "summary": {
      "max_lon": 24.749653,
      "max_lat": 59.441212,
      "time": 493,
      "length": 1.674,
      "min_lat": 59.435513,
      "min_lon": 24.742632
    },
    "locations": [
      {
        "lon": 24.742596,
        "lat": 59.436886,
        "type": "break"
      },
      {
        "side_of_street": "right",
        "lon": 24.747604,
        "lat": 59.435562,
        "type": "break"
      }
    ],
    "units": "kilometers",
    "legs": [
      {
        "shape": "ssvjpBmmden@cFiF{A{A_DgCsFuEoIkFiCi@eEe@iHS?tHwWq@WuMeOm_@yH}QwCoHm@{AaCsFsFeMeZy\\yBgBa\\yScVeRqGaFyCsDgCaEiMgScBwC_I{NoSwSrPclAjGhJhLnQnc@l\\bQvNtIrEFBlKvFjFdCd@Ct@kAG_B]sAoD}FsAyBwS{]aa@ch@TqETgDFuB?oBGeBEwAz@wAbA{AbBcAjGS~H?lJd@pRlCbUbDtEd@dFpCxGlIpGrIjB{Md@yEl@aHr@}Jl@wP\\mWzFsAzAUd@Tl@Rx\\q@xB?pBcAdKxAxL~A|Dh@hCh@fNrCxBh@nIbBpGpBtEdChBnArAbBrAdB~DrIzFrSfD|OLv@hHd_@rArF",
        "summary": {
          "max_lon": 24.749653,
          "max_lat": 59.441212,
          "time": 493,
          "length": 1.674,
          "min_lat": 59.435513,
          "min_lon": 24.742632
        },
        "maneuvers": [
          {
            "travel_mode": "drive",
            "begin_shape_index": 0,
            "length": 0.109,
            "time": 30,
            "type": 1,
            "end_shape_index": 9,
            "instruction": "Drive northeast on Rataskaevu.",
            "verbal_pre_transition_instruction": "Drive northeast on Rataskaevu for 100 meters.",
            "travel_type": "car",
            "street_names": [
              "Rataskaevu"
            ]
          },
          {
            "travel_type": "car",
            "travel_mode": "drive",
            "verbal_multi_cue": true,
            "verbal_pre_transition_instruction": "Turn right onto Nunne. Then Turn right onto Lai.",
            "verbal_transition_alert_instruction": "Turn right onto Nunne.",
            "length": 0.044,
            "instruction": "Turn right onto Nunne.",
            "end_shape_index": 10,
            "type": 10,
            "time": 11,
            "verbal_post_transition_instruction": "Continue for 40 meters.",
            "street_names": [
              "Nunne"
            ],
            "begin_shape_index": 9
          },
          {
            "travel_type": "car",
            "travel_mode": "drive",
            "verbal_pre_transition_instruction": "Turn right onto Lai.",
            "verbal_transition_alert_instruction": "Turn right onto Lai.",
            "length": 0.425,
            "instruction": "Turn right onto Lai.",
            "end_shape_index": 28,
            "type": 10,
            "time": 80,
            "verbal_post_transition_instruction": "Continue for 400 meters.",
            "street_names": [
              "Lai"
            ],
            "begin_shape_index": 10
          },
          {
            "travel_type": "car",
            "travel_mode": "drive",
            "verbal_multi_cue": true,
            "verbal_pre_transition_instruction": "Turn right onto Oleviste. Then Turn right onto Pikk.",
            "verbal_transition_alert_instruction": "Turn right onto Oleviste.",
            "length": 0.077,
            "instruction": "Turn right onto Oleviste.",
            "end_shape_index": 29,
            "type": 10,
            "time": 13,
            "verbal_post_transition_instruction": "Continue for 80 meters.",
            "street_names": [
              "Oleviste"
            ],
            "begin_shape_index": 28
          },
          {
            "travel_type": "car",
            "travel_mode": "drive",
            "rough": true,
            "verbal_pre_transition_instruction": "Turn right onto Pikk.",
            "verbal_transition_alert_instruction": "Turn right onto Pikk.",
            "length": 0.213,
            "instruction": "Turn right onto Pikk.",
            "end_shape_index": 38,
            "type": 10,
            "time": 81,
            "verbal_post_transition_instruction": "Continue for 200 meters.",
            "street_names": [
              "Pikk"
            ],
            "begin_shape_index": 29
          },
          {
            "travel_type": "car",
            "travel_mode": "drive",
            "verbal_multi_cue": true,
            "rough": true,
            "verbal_pre_transition_instruction": "Turn left to stay on Pikk. Then Turn left onto Olevimägi.",
            "verbal_transition_alert_instruction": "Turn left to stay on Pikk.",
            "length": 0.004,
            "instruction": "Turn left to stay on Pikk.",
            "end_shape_index": 39,
            "type": 15,
            "time": 12,
            "verbal_post_transition_instruction": "Continue for less than 10 meters.",
            "street_names": [
              "Pikk"
            ],
            "begin_shape_index": 38
          },
          {
            "travel_type": "car",
            "travel_mode": "drive",
            "verbal_pre_transition_instruction": "Turn left onto Olevimägi.",
            "verbal_transition_alert_instruction": "Turn left onto Olevimägi.",
            "length": 0.141,
            "instruction": "Turn left onto Olevimägi.",
            "end_shape_index": 45,
            "type": 15,
            "time": 30,
            "verbal_post_transition_instruction": "Continue for 100 meters.",
            "street_names": [
              "Olevimägi"
            ],
            "begin_shape_index": 39
          },
          {
            "travel_type": "car",
            "travel_mode": "drive",
            "verbal_multi_cue": true,
            "verbal_pre_transition_instruction": "Turn right to stay on Olevimägi. Then Turn right onto Vene.",
            "verbal_transition_alert_instruction": "Turn right to stay on Olevimägi.",
            "length": 0.023,
            "instruction": "Turn right to stay on Olevimägi.",
            "end_shape_index": 51,
            "type": 10,
            "time": 12,
            "verbal_post_transition_instruction": "Continue for 20 meters.",
            "street_names": [
              "Olevimägi"
            ],
            "begin_shape_index": 45
          },
          {
            "travel_type": "car",
            "travel_mode": "drive",
            "verbal_pre_transition_instruction": "Turn right onto Vene.",
            "verbal_transition_alert_instruction": "Turn right onto Vene.",
            "length": 0.204,
            "instruction": "Turn right onto Vene.",
            "end_shape_index": 63,
            "type": 10,
            "time": 58,
            "verbal_post_transition_instruction": "Continue for 200 meters.",
            "street_names": [
              "Vene"
            ],
            "begin_shape_index": 51
          },
          {
            "travel_type": "car",
            "travel_mode": "drive",
            "verbal_multi_cue": true,
            "verbal_pre_transition_instruction": "Turn left onto Munga. Then Turn right onto Müürivahe.",
            "verbal_transition_alert_instruction": "Turn left onto Munga.",
            "length": 0.08,
            "instruction": "Turn left onto Munga.",
            "end_shape_index": 69,
            "type": 15,
            "time": 20,
            "verbal_post_transition_instruction": "Continue for 80 meters.",
            "street_names": [
              "Munga"
            ],
            "begin_shape_index": 63
          },
          {
            "travel_type": "car",
            "travel_mode": "drive",
            "verbal_pre_transition_instruction": "Turn right onto Müürivahe.",
            "verbal_transition_alert_instruction": "Turn right onto Müürivahe.",
            "length": 0.353,
            "instruction": "Turn right onto Müürivahe.",
            "end_shape_index": 94,
            "type": 10,
            "time": 146,
            "verbal_post_transition_instruction": "Continue for 400 meters.",
            "street_names": [
              "Müürivahe"
            ],
            "begin_shape_index": 69
          },
          {
            "travel_type": "car",
            "travel_mode": "drive",
            "begin_shape_index": 94,
            "time": 0,
            "type": 5,
            "end_shape_index": 94,
            "instruction": "Your destination is on the right.",
            "length": 0,
            "verbal_transition_alert_instruction": "Your destination will be on the right.",
            "verbal_pre_transition_instruction": "Your destination is on the right."
          }
        ]
      }
    ],
    "status_message": "Found route between points",
    "status": 0
  }
}

Further reading

The Valhalla project is the official source of documentation. You should be able to find what you're looking for there.