Routing docs

Routing quickstart

A first request to each geolith routing endpoint at api.geolith.app: /v1/route, /v1/sources-to-targets, /v1/isochrone, /v1/trace-route and /v1/trace-attributes, with curl and JavaScript fetch. Secret key, Valhalla bodies, 10 cities.

By · Updated

Routing is available in 10 cities. Every location of one request must be inside one city. See Coverage and errors.

  1. Sign up at console.geolith.app/signup and create a secret key (gc_sk_…). Routing refuses publishable keys and OAuth tokens.
  2. Send the request from a server. Replace YOUR_API_KEY.
  3. 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 example bengaluru.
  • X-Routing-Build: the build date of that city's data (yyyy-mm-dd).
  • X-Routing-Units: the routing units this request used, 0 for 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.