---
title: "Compute a turn-by-turn route"
method: POST
path: "/route"
tags: ["navigation"]
---

# Compute a turn-by-turn route

`POST /route`

## Request

- Base URL: `https://api.mapsource.io`
- URL: `https://api.mapsource.io/route`
- Auth: HTTP bearer

A route between 2 and 10 waypoints on the global road graph, optionally with a sampled elevation profile.

When to use: Retrieve route geometry, directions, distance, and travel time between waypoints.

When not to use: Use a matrix for travel-time comparisons across multiple origins and destinations.

## Request body

- object
  - `locations` unknown[], required: Ordered waypoints; first is origin, last is destination.
    - unknown
  - `costing` 'auto' | 'bicycle' | 'pedestrian' | 'truck' | 'motor_scooter' | 'bus': Travel mode.
  - `elevation` boolean: Also return a terrain profile with gain and loss.

## Response `200`

Compute a turn-by-turn route

- object
  - `schema` string
  - `profile` string: The costing model that produced this result.
  - `units` object
    - `distance` string
    - `duration` string
  - `graph` object
    - `engine` string
    - `tilesetBuiltAt` string, nullable
  - `geometryAvailable` 'inline' | 'handle': Where the geometry is. handle means read geometryRef.
  - `meta` object
    - `requestId` string
    - `computeMs` integer
    - `requestedAt` string, date-time
    - `sources` object[]
      - `dataset` string
      - `observedAt` string, nullable
      - `license` string
    - `freshness` object, nullable
    - `licenses` string[]
    - `attribution` string[]
  - `costing` string: Travel profile; equivalent to profile.
  - `summary` object
    - `distanceKm` number
    - `durationSeconds` integer
  - `geometry` object: GeoJSON. Omitted when the route is large enough to be handle-backed; read geometryRef then.
  - `geometryRef` string, nullable: A result handle holding the geometry, when it was too large to inline.
  - `maneuvers` unknown[]
    - unknown
  - `elevation` object: Present when elevation was requested: samples, gain, loss, and the sampling and smoothing method used.

## Other responses

- `400`: Error with a stable machine code.
- `401`: Error with a stable machine code.
- `429`: Error with a stable machine code.
- `500`: Error with a stable machine code.

---

[API](https://skmtc.dev/mapsource/apis/mapsource-overpass-api.md) · [All operations](https://skmtc.dev/mapsource/apis/mapsource-overpass-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mapsource/apis/mapsource-overpass-api/revisions/8af8c2769e7b?raw)