# 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.

Routing is available in 10 cities. Every location of one request must be inside one city. See [Coverage and errors](/routing/coverage-and-errors).

1. Sign up at [console.geolith.app/signup](https://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.

```bash
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"
  }'
```

```js
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.

```bash
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"
  }'
```

```js
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.

```bash
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
  }'
```

```js
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](/routing/limits-and-units#limits-per-city).

## Map matching

A short GPS trace in Berlin, matched to the roads. `/v1/trace-attributes` takes the same body.

```bash
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"
  }'
```

```js
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

```bash
curl "https://api.geolith.app/v1/routing/coverage" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```js
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](/routing/api), [Coverage and errors](/routing/coverage-and-errors) and [Limits, units and plans](/routing/limits-and-units).
