Routing

Stadia Maps provides turn-by-turn navigation with frequent data updates, 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's daily soft 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 (auto), bicycle (bicycle), and pedestrian (pedestrian). Valhalla refers to this as the costing model.

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. This code snipped assumes you have installed the requests module (you really should if you're doing HTTP requests; it's amazing!).

import requests

def get_route_between_two_points(start_lat, start_lon, end_lat, end_lon, costing='auto'):
    params = {
        'api_key': YOUR_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.

Miscellaneous technical notes

We guarantee that our data will be no more than 1 week behind the current OSM data. We also closely track the latest stable Valhalla codebase on a weekly or better basis, and are ourselves contributors to the project. If you are a Stadia Maps user and notice an issue, please report it via the Valhalla GitHub issue tracker, but also feel free to send us an email. While we do not offer any kind of guarantees, in the past we have often been able to fix issues quickly and submit a patch upstream. Our developers regularly monitor the upstream pull requests as well, and we occasionally cherry pick low breakage risk and high priority bug fixes before they make it into an official release.