Routing docs

Routing limits, units and plans

How geolith routing is counted: routing units per request (route 1, matrix sources × targets, isochrone contours, map matching per 100 points), the monthly routing allowance of each plan (Free 10,000 to Scale 1,000,000), rate limits, and the limits of one request. Available in 10 cities.

By · Updated

Routing is in every plan, with its own monthly allowance. Plan prices do not change. Routing is available in 10 cities; see Coverage and errors.

Allowances per plan

PlanUnits a monthRequests a second
Free10,0002
Starter50,0005
Growth250,00010
Scale1,000,00025

Units are routing units. Requests a second are routing requests per key.

  • The routing allowance is separate from the geocoding and map-tile allowances. See Quotas and errors for those and for the prices.
  • The month is the calendar month in UTC.
  • At the allowance, routing stops with 429 quota_exceeded until the month ends or you upgrade. There are no overage charges.
  • A routing request also counts against the plan's per-key request rate.
  • All free accounts together share a daily routing capacity. When it is reached, free requests get 429 quota_exceeded with "reason": "free_daily_ceiling" until 00:00 UTC. Paid plans are not affected.

Routing units

Only answers with status 2xx use units. Errors use none.

EndpointUnits, and the largest request
/v1/route1. Valhalla's location limits apply.
/v1/sources-to-targetssources × targets, at most 625 cells, within the city's limits.
/v1/isochrone1 per contour, at most 4 contours, within the city's limits.
/v1/trace-route, /v1/trace-attributes1 per 100 trace points, started. At most 16,000 points and 1 MiB of body, within the city's limits.
/v1/routing/coverage0. Any API key.

Examples:

  • A route with 5 locations: 1 unit.
  • A matrix of 10 sources and 20 targets: 200 units.
  • An isochrone with contours at 10, 20 and 30 minutes: 3 units.
  • A trace of 100 points: 1 unit. A trace of 101 points: 2 units. A trace of 16,000 points: 160 units.

Counting. The service counts the units from the request before it asks the router. A request that needs more units than are left is refused whole. After a 2xx answer, the X-Routing-Units header gives the units used, and X-Quota-Remaining the units left.

Limits

These limits apply at launch. They are not bugs. They will change; see Status and roadmap.

  • One city per request. All locations of one request must be inside one city. Outside every city: error 1001. In two cities: error 1002.
  • 64 MiB of map data per request. One request may read at most 64 MiB of map data. Long walking routes that use a ferry, and a few requests with no possible route, can need more map data or memory than one request may use, or would take too long, and get error 1004. Car routes inside a city were not refused in testing. Shorten the route or split it. A 1004 answer uses no routing units.
  • No traffic. Speeds are default speeds per road class and country. There is no live or historical traffic. See Speeds and traffic.
  • No arrive-by time. date_time types 0 (current) and 1 (depart at) work. Types 2 (arrive by) and 3 (invariant) get error 199.
  • Secret keys only. Publishable keys and OAuth tokens get 403 secret_key_required. Call routing from your server.
  • English instructions only.
  • Request size. A matrix may have at most 625 cells and an isochrone at most 4 contours (400 invalid_request), within the city's limits below. A body may be at most 1 MiB (413 payload_too_large).

Limits per city

Each city has its own service limits for isochrones, map matching and matrices. /v1/route has none of these; it keeps the 64 MiB limit above.

The hosted router runs on Cloudflare Workers with a fixed memory per request, and dense city centres hold more road data per kilometre, so the limits differ by city. Each limit is one step below the largest value that every test request in that city answered. San Francisco's car isochrone limit, 1 minute, is the smallest value tested. Limits can rise without any change in your client.

  • Bengaluru

    Isochrone minutes (auto / bicycle / pedestrian)
    15 / 15 / 60
    Distance contour km (auto / bicycle / pedestrian)
    1 / 0 / 0
    Trace km
    30
    Matrix span km (≤25 / ≤100 / ≤625 cells)
    20 / 20 / 10
  • Mumbai

    Isochrone minutes (auto / bicycle / pedestrian)
    20 / 45 / 60
    Distance contour km (auto / bicycle / pedestrian)
    10 / 5 / 7
    Trace km
    30
    Matrix span km (≤25 / ≤100 / ≤625 cells)
    20 / 20 / 20
  • Delhi

    Isochrone minutes (auto / bicycle / pedestrian)
    20 / 20 / 60
    Distance contour km (auto / bicycle / pedestrian)
    1 / 1 / 2
    Trace km
    30
    Matrix span km (≤25 / ≤100 / ≤625 cells)
    20 / 20 / 10
  • London

    Isochrone minutes (auto / bicycle / pedestrian)
    5 / 5 / 20
    Distance contour km (auto / bicycle / pedestrian)
    0 / 0 / 0
    Trace km
    10
    Matrix span km (≤25 / ≤100 / ≤625 cells)
    10 / 10 / 5
  • Berlin

    Isochrone minutes (auto / bicycle / pedestrian)
    2 / 5 / 30
    Distance contour km (auto / bicycle / pedestrian)
    0 / 0 / 0
    Trace km
    5
    Matrix span km (≤25 / ≤100 / ≤625 cells)
    5 / 5 / 2
  • Paris

    Isochrone minutes (auto / bicycle / pedestrian)
    2 / 5 / 30
    Distance contour km (auto / bicycle / pedestrian)
    0 / 0 / 0
    Trace km
    2
    Matrix span km (≤25 / ≤100 / ≤625 cells)
    10 / 2 / 2
  • New York

    Isochrone minutes (auto / bicycle / pedestrian)
    2 / 15 / 30
    Distance contour km (auto / bicycle / pedestrian)
    0 / 0 / 0
    Trace km
    10
    Matrix span km (≤25 / ≤100 / ≤625 cells)
    10 / 5 / 2
  • San Francisco Bay Area

    Isochrone minutes (auto / bicycle / pedestrian)
    1 / 15 / 45
    Distance contour km (auto / bicycle / pedestrian)
    1 / 0 / 0
    Trace km
    15
    Matrix span km (≤25 / ≤100 / ≤625 cells)
    20 / 10 / 5
  • Singapore

    Isochrone minutes (auto / bicycle / pedestrian)
    5 / 20 / 60
    Distance contour km (auto / bicycle / pedestrian)
    1 / 1 / 0
    Trace km
    30
    Matrix span km (≤25 / ≤100 / ≤625 cells)
    20 / 10 / 10
  • Tokyo

    Isochrone minutes (auto / bicycle / pedestrian)
    3 / 10 / 30
    Distance contour km (auto / bicycle / pedestrian)
    0 / 0 / 0
    Trace km
    5
    Matrix span km (≤25 / ≤100 / ≤625 cells)
    10 / 5 / 2

How to read the table:

  • Isochrone minutes: the largest contour time, for auto, bicycle and pedestrian.
  • Distance contour km: the largest contour distance. 0 means the city serves no distance contours for that costing.
  • Trace km: the longest trace, measured as straight lines between its points.
  • Matrix span km: the longest distance between any source and target, for a matrix of at most 25, 100 or 625 cells.
  • Everywhere: at most 4 contours, 16,000 trace points and 625 matrix cells.

A request over a limit is refused at once with Valhalla's own limit error, HTTP 400, and uses no routing units. See Over a city's limits for the codes and example bodies.

The same limits are in the coverage answer, as limits per city (GET /v1/routing/coverage, any API key). See The coverage GeoJSON.