Routing is available in 10 cities. Planet coverage comes later. Every location of one request must be inside one city.
The cities
Each city covers its continuous built-up area plus 15 km on every side, rounded out to 0.05°.
| City | Country | Id |
|---|---|---|
| Bengaluru | IN | bengaluru |
| Mumbai | IN | mumbai |
| Delhi | IN | delhi |
| London | GB | london |
| Berlin | DE | berlin |
| Paris | FR | paris |
| New York | US | new-york |
| San Francisco Bay Area | US | san-francisco |
| Singapore | SG | singapore |
| Tokyo | JP | tokyo |
The bounds of each city, by id, as [west, south, east, north] in degrees:
{
"bengaluru": [77.25, 12.65, 78.0, 13.35],
"mumbai": [72.6, 18.75, 73.4, 19.65],
"delhi": [76.7, 28.2, 77.7, 29.05],
"london": [-0.75, 51.15, 0.55, 51.85],
"berlin": [12.75, 52.15, 14.05, 52.85],
"paris": [1.75, 48.5, 2.95, 49.2],
"new-york": [-74.55, 40.3, -73.35, 41.2],
"san-francisco": [-122.7, 37.05, -121.6, 38.2],
"singapore": [103.45, 1.15, 104.25, 1.75],
"tokyo": [139.15, 35.15, 140.3, 36.1]
}
- Delhi includes Gurugram, Faridabad, Noida, Greater Noida and Ghaziabad.
- Mumbai includes Thane, Navi Mumbai, Kalyan-Dombivli, Vasai-Virar and Panvel.
- Bengaluru includes Hosur.
- Singapore includes the Johor Bahru built-up area. It has no Indonesian roads.
- The San Francisco Bay Area includes Oakland, Berkeley, Fremont and San Jose.
The coverage GeoJSON is the source of truth. The table can lag behind it.
The coverage GeoJSON
curl "https://api.geolith.app/v1/routing/coverage" \
-H "Authorization: Bearer YOUR_API_KEY"
GETonly. It needs an API key: a secret key, or a publishable key from one of its allowed origins, so a map in the browser can draw the cities.- No key or a bad key gets
401. A publishable key from another origin gets403 origin_not_allowed. - Each city carries its service
limits(Limits per city). - It costs no routing units and uses no allowance (
X-Routing-Units: 0). It counts against the key's normal request rate. - Answers may be kept for 5 minutes (
Cache-Control: private, max-age=300). - The answer is a GeoJSON FeatureCollection with one feature per city, sorted by id.
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"id": "bengaluru",
"bbox": [77.25, 12.65, 78, 13.35],
"properties": {
"id": "bengaluru",
"name": "Bengaluru",
"country": "IN",
"built": "2026-11-16",
"limits": {
"isochrone_minutes": { "auto": 15, "bicycle": 15, "pedestrian": 60 },
"isochrone_km": { "auto": 1, "bicycle": 1, "pedestrian": 0 },
"trace_km": 30,
"matrix_span_km": { "25": 20, "100": 20, "625": 10 }
}
},
"geometry": {
"type": "Polygon",
"coordinates": [
[
[77.25, 12.65],
[78, 12.65],
[78, 13.35],
[77.25, 13.35],
[77.25, 12.65]
]
]
}
}
]
}
built is the build date of the city's data. The X-Routing-Build header of an answer carries the same date. limits are the city's service limits, the same as the table in Limits per city.
Which city answers. A request goes to the one city that holds all its locations: route locations, matrix sources and targets, the isochrone location, and every trace point. If two cities hold them all, the smaller city answers. The X-Routing-City header names the city.
Two error shapes
Routing errors come in two shapes.
- Errors from the router keep Valhalla's body:
error_code,error,status_codeandstatus. These are coverage errors and request errors. - Errors from api.geolith.app use the
errorobject of every geolith API:code,messageanddocs. These are key, quota, rate and size errors. See Quotas and errors.
No error uses routing units. An error from the router carries X-Routing-Units: 0.
Coverage errors
1001: outside coverage
A location is in no city. HTTP 400.
{
"error_code": 1001,
"error": "Location is outside routing coverage. Covered cities: Bengaluru, Berlin, Delhi, London, Mumbai, New York, Paris, San Francisco Bay Area, Singapore, Tokyo. See https://docs.geolith.app/routing/coverage-and-errors",
"status_code": 400,
"status": "Bad Request"
}
Check the location against the coverage GeoJSON. Do not retry the same request.
1002: locations in different cities
Every location is in a city, but no one city holds them all. HTTP 400. Routes between cities are not served yet.
{
"error_code": 1002,
"error": "Locations are in different cities (Berlin, Paris): routing between cities is not served yet. See https://docs.geolith.app/routing/coverage-and-errors",
"status_code": 400,
"status": "Bad Request"
}
Split the request so that each part stays in one city.
1004: too heavy for one request
HTTP 400. A request gets 1004 when it would pass one of three limits: it needs more than 64 MiB of map data, it needs more memory than one request may use, or it would take too long. Long walking routes that use a ferry can do this, and so can a few requests with no possible route. Car routes inside a city were not refused in testing. A 1004 answer uses no routing units. The answer does not say which limit was reached: the body is the same for all three.
{
"error_code": 1004,
"error": "This request needs more map data than one request may read (for example a long walking route that uses a ferry). Shorten the route or split it.",
"status_code": 400,
"status": "Bad Request"
}
Shorten the route or split it into legs.
Over a city's limits
Each city has service limits: isochrone time and distance, trace length and matrix span. See Limits per city. A request over a limit is refused at once, before any map data is read. The answer is HTTP 400 with Valhalla's own limit error. It uses no routing units.
| Code | When, and the message |
|---|---|
150 | A matrix over 625 cells. Exceeded max locations: 625.000000 |
151 | An isochrone time over the city's limit for its costing. Exceeded max time: <minutes> |
152 | More than 4 isochrone contours. Exceeded max contours: 4 |
153 | A trace with more than 16,000 points. Too many shape points: (<n>). The limit is 16000 |
154 | A trace longer than the city's limit, or a matrix pair farther apart than its span. Path distance exceeds the max distance limit: <metres> meters |
166 | An isochrone distance over the city's limit; 0 means no distance contours. Exceeded max distance: <km> |
A car isochrone of 10 minutes in Paris (limit 2 minutes):
{
"error_code": 151,
"error": "Exceeded max time: 2",
"status_code": 400,
"status": "Bad Request"
}
A trace of 3 km in Paris (limit 2 km):
{
"error_code": 154,
"error": "Path distance exceeds the max distance limit: 2000 meters",
"status_code": 400,
"status": "Bad Request"
}
Make the request smaller, or split it. Do not retry it as is.
Request errors from the router
Every other router error is Valhalla's own code and message, with HTTP 400. Common ones:
| Code | When |
|---|---|
171 | No road near a location (No suitable edges near location) |
199 | A date_time of type 2 (arrive by) or 3 (invariant) |
Fix the request. Do not retry it as is.
Errors from api.geolith.app
{
"error": {
"code": "secret_key_required",
"message": "Routing takes a secret key (gc_sk_…) from a server; publishable keys and OAuth tokens are refused.",
"docs": "https://docs.geolith.app/search/hosted/quotas-and-errors#errors"
}
}
| Status | Code | When, and what to do |
|---|---|---|
| 400 | invalid_request | A matrix over 625 cells, or an isochrone over 4 contours. Make the request smaller. |
| 401 | missing_api_key | No key. Send Authorization: Bearer or api_key. |
| 401 | invalid_api_key | Malformed, unknown or revoked key. Check the key in the dashboard. |
| 403 | secret_key_required | A publishable key or an OAuth token. Use a secret key from a server. |
| 403 | email_not_verified | The account has not verified its email. Verify it at console.geolith.app. |
| 405 | method_not_allowed | Not GET, POST or OPTIONS. Use POST with a JSON body. |
| 413 | payload_too_large | A body over 1 MiB (1,048,576 bytes). Send a shorter trace. |
| 429 | rate_limited | More routing requests a second than your plan allows. Wait for Retry-After and retry. |
| 429 | quota_exceeded | The routing allowance has fewer units left than the request needs. Wait for the next month or upgrade; do not retry. |
| 503 | service_unavailable | A fault on our side. Wait for Retry-After (1 s) and retry. |
A quota_exceeded answer for routing carries "product": "routing":
{
"error": {
"code": "quota_exceeded",
"message": "Monthly routing allowance of 10000 units on the Free plan has fewer units left than this request needs (12 left).",
"product": "routing",
"reason": "allowance",
"docs": "https://docs.geolith.app/search/hosted/quotas-and-errors#errors"
}
}
reason is free_daily_ceiling when all free accounts together reached the day's free routing capacity. It resets at 00:00 UTC. Paid plans are not affected.
A request that needs more units than are left is refused whole. The service never answers part of a matrix.