# Routing API (not callable yet)

> The six Valhalla-compatible endpoints the geolith router answers: /route, /isochrone, /sources-to-targets, /trace-route, /trace-attributes and /status, with one example each. Costing auto, pedestrian and bicycle. Not deployed for public use: there is no endpoint to call yet.

**Status: in development, not deployed for public use. None of these endpoints is callable yet.** Neither geolith.app nor api.geolith.app answers them, and there is no hosted API and no pricing. The router answers every example below on a test deployment; this page describes the bodies so you can check a client against them.

## Valhalla-compatible

Request and response bodies are Valhalla's, as documented in the [Valhalla API reference](https://valhalla.github.io/valhalla/api/turn-by-turn/api-reference/). Paths are kebab-case only: a Valhalla client changes only the path (for example `/sources_to_targets` becomes `/sources-to-targets`). Each endpoint takes the request JSON as a `POST` body, or as `?json=` on a `GET`.

| Endpoint              | Answers                                          |
| --------------------- | ------------------------------------------------ |
| `/route`              | A route between two or more locations            |
| `/isochrone`          | Areas reachable within a time or a distance      |
| `/sources-to-targets` | A time and distance matrix                       |
| `/trace-route`        | A route matched to a GPS trace                   |
| `/trace-attributes`   | The edges and their attributes along a GPS trace |
| `/status`             | The service version and the available actions    |

- **Costing:** `auto`, `pedestrian` and `bicycle`.
- **Time:** `date_time` types `0` (current) and `1` (depart at) use historical speeds; see [Traffic and live data](/routing/traffic). Types `2` (arrive by) and `3` (invariant) return error `199` for now.
- **Traffic:** live speeds and closures are supplied by the program that runs the router. No hosted service collects them.
- **Instructions:** maneuvers carry text and spoken (`verbal_*`) instructions, in English only.

`ROUTER_HOST` below stands for a router you run yourself; see [Self-hosting](/routing/self-hosting). The examples show the requests; the responses are Valhalla's shapes.

## /route

```bash
curl -X POST "https://ROUTER_HOST/route" \
  -H "Content-Type: application/json" \
  -d '{
    "locations": [
      { "lat": 52.5163, "lon": 13.3777 },
      { "lat": 52.5079, "lon": 13.3376 }
    ],
    "costing": "auto",
    "units": "kilometers"
  }'
```

The response is a `trip` with its `legs`, each with `maneuvers`, a `summary` (length and time) and a `shape` encoded as a polyline with precision 6.

## /isochrone

```bash
curl -X POST "https://ROUTER_HOST/isochrone" \
  -H "Content-Type: application/json" \
  -d '{
    "locations": [{ "lat": 52.5163, "lon": 13.3777 }],
    "costing": "pedestrian",
    "contours": [{ "time": 10 }],
    "polygons": true
  }'
```

The response is GeoJSON: one feature per contour, as lines or polygons.

## /sources-to-targets

```bash
curl -X POST "https://ROUTER_HOST/sources-to-targets" \
  -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"
  }'
```

The response holds the time and distance from every source to every target.

## /trace-route

```bash
curl -X POST "https://ROUTER_HOST/trace-route" \
  -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"
  }'
```

The response is a `trip`, like `/route`, along the matched roads.

## /trace-attributes

```bash
curl -X POST "https://ROUTER_HOST/trace-attributes" \
  -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"
  }'
```

The response lists the matched edges with their attributes and the matched points.

## /status

```bash
curl "https://ROUTER_HOST/status"
```

```json
{
  "version": "3.9.1",
  "available_actions": [
    "status",
    "route",
    "isochrone",
    "sources-to-targets",
    "trace-route",
    "trace-attributes"
  ],
  "tileset_last_modified": 1794106434
}
```

## Errors

Errors take Valhalla's error body: `error_code`, `error`, `status_code` and `status`. For example, a `date_time` of type `2` or `3` returns error `199`.