Routing is available in 10 cities. Every location of one request must be inside one city. See Coverage and errors.
- Sign up at console.geolith.app/signup and create a secret key (
gc_sk_…). Routing refuses publishable keys and OAuth tokens. - Send the request from a server. Replace
YOUR_API_KEY. - Read the Valhalla response body.
Send the key as Authorization: Bearer YOUR_API_KEY or as ?api_key=YOUR_API_KEY. Send the request JSON as a POST body, or as ?json= on a GET.
Route
A car route in Bengaluru.
curl -X POST "https://api.geolith.app/v1/route" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"locations": [
{ "lat": 12.9756, "lon": 77.6066 },
{ "lat": 12.9352, "lon": 77.6245 }
],
"costing": "auto",
"units": "kilometers"
}'
const res = await fetch('https://api.geolith.app/v1/route', {
method: 'POST',
headers: {
Authorization: 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json',
},
body: JSON.stringify({
locations: [
{ lat: 12.9756, lon: 77.6066 },
{ lat: 12.9352, lon: 77.6245 },
],
costing: 'auto',
units: 'kilometers',
}),
});
if (!res.ok) throw new Error(`geolith ${res.status}: ${await res.text()}`);
const { trip } = await res.json();
console.log(trip.summary.length, 'km,', trip.summary.time, 's');
The answer is a Valhalla trip. trip.summary has the length (in units) and the time in seconds. Each leg has maneuvers and a shape, a polyline with precision 6.
Matrix
Times and distances from one source to two targets in Berlin.
curl -X POST "https://api.geolith.app/v1/sources-to-targets" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"sources": [{ "lat": 52.5163, "lon": 13.3777 }],
"targets": [
{ "lat": 52.5079, "lon": 13.3376 },
{ "lat": 52.5200, "lon": 13.4050 }
],
"costing": "auto"
}'
const res = await fetch('https://api.geolith.app/v1/sources-to-targets', {
method: 'POST',
headers: {
Authorization: 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json',
},
body: JSON.stringify({
sources: [{ lat: 52.5163, lon: 13.3777 }],
targets: [
{ lat: 52.5079, lon: 13.3376 },
{ lat: 52.52, lon: 13.405 },
],
costing: 'auto',
}),
});
if (!res.ok) throw new Error(`geolith ${res.status}: ${await res.text()}`);
const { sources_to_targets } = await res.json();
for (const cell of sources_to_targets[0])
console.log(cell.to_index, cell.time, cell.distance);
This request costs 2 routing units (1 source × 2 targets).
Isochrone
The area you can walk to in 10 minutes from the Eiffel Tower.
curl -X POST "https://api.geolith.app/v1/isochrone" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"locations": [{ "lat": 48.8584, "lon": 2.2945 }],
"costing": "pedestrian",
"contours": [{ "time": 10 }],
"polygons": true
}'
const res = await fetch('https://api.geolith.app/v1/isochrone', {
method: 'POST',
headers: {
Authorization: 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json',
},
body: JSON.stringify({
locations: [{ lat: 48.8584, lon: 2.2945 }],
costing: 'pedestrian',
contours: [{ time: 10 }],
polygons: true,
}),
});
if (!res.ok) throw new Error(`geolith ${res.status}: ${await res.text()}`);
const areas = await res.json(); // GeoJSON FeatureCollection, one feature per contour
console.log(areas.features.length);
The answer is GeoJSON. You can add it to a MapLibre map as a geojson source.
Every example here is inside its city's limits. Matrix span, isochrone time and trace length are capped per city: see Limits per city.
Map matching
A short GPS trace in Berlin, matched to the roads. /v1/trace-attributes takes the same body.
curl -X POST "https://api.geolith.app/v1/trace-route" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"shape": [
{ "lat": 52.5163, "lon": 13.3777 },
{ "lat": 52.5160, "lon": 13.3740 },
{ "lat": 52.5155, "lon": 13.3700 }
],
"costing": "auto",
"shape_match": "map_snap"
}'
const res = await fetch('https://api.geolith.app/v1/trace-attributes', {
method: 'POST',
headers: {
Authorization: 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json',
},
body: JSON.stringify({
shape: [
{ lat: 52.5163, lon: 13.3777 },
{ lat: 52.516, lon: 13.374 },
{ lat: 52.5155, lon: 13.37 },
],
costing: 'auto',
shape_match: 'map_snap',
}),
});
if (!res.ok) throw new Error(`geolith ${res.status}: ${await res.text()}`);
const { edges, matched_points } = await res.json();
console.log(edges.length, matched_points.length);
A trace costs 1 routing unit per 100 points, started. These 3 points cost 1 unit.
Coverage
curl "https://api.geolith.app/v1/routing/coverage" \
-H "Authorization: Bearer YOUR_API_KEY"
const res = await fetch('https://api.geolith.app/v1/routing/coverage', {
headers: { Authorization: 'Bearer YOUR_API_KEY' },
});
const coverage = await res.json(); // GeoJSON FeatureCollection
console.log(coverage.features.map((f) => f.properties.name));
This endpoint takes any API key. A publishable key works from its allowed origins, so a browser map can draw the cities. It costs no routing units.
Response headers
Every routing answer carries these headers:
X-Routing-City: the city that answered, for examplebengaluru.X-Routing-Build: the build date of that city's data (yyyy-mm-dd).X-Routing-Units: the routing units this request used,0for an error.X-Quota-Product:routing.X-Quota-Limit: routing units a month on your plan.X-Quota-Remaining: routing units left this month.
Next: the API reference, Coverage and errors and Limits, units and plans.