---
title: "Turn-by-turn directions."
method: POST
path: "/directions/v1"
tags: ["Routing"]
---

# Turn-by-turn directions.

`POST /directions/v1`

## Request

- Base URL: `https://api.rijwind.com`
- URL: `https://api.rijwind.com/directions/v1`
- Auth: HTTP bearer

Calculate a route between two or more waypoints.

**Quota cost:** 1 unit per call.

## Request body

- RouteRequest
  - `costing` 'auto' | 'bicycle' | 'pedestrian', required: Routing profile. `auto` (car), `bicycle`, or `pedestrian` (foot).
  - `costingOptions` CostingOptions: Profile-specific options, keyed by the profile they apply to. Only the entry matching `costing` is used.
    - `auto` ProfileOptions
      - `excludeFerries` boolean, nullable: Exclude ferries entirely. The route then never uses a ferry, and waypoints never snap onto one; if no route exists without a ferry, the request fails.
      - `useFerry` number, double, nullable: Preference for ferries, from `0` (avoid when possible) to `1` (prefer). A preference only: a ferry is still used when there is no reasonable alternative. Defaults to `0.5`.
    - `bicycle` ProfileOptions
      - `excludeFerries` boolean, nullable: Exclude ferries entirely. The route then never uses a ferry, and waypoints never snap onto one; if no route exists without a ferry, the request fails.
      - `useFerry` number, double, nullable: Preference for ferries, from `0` (avoid when possible) to `1` (prefer). A preference only: a ferry is still used when there is no reasonable alternative. Defaults to `0.5`.
    - `pedestrian` ProfileOptions
      - `excludeFerries` boolean, nullable: Exclude ferries entirely. The route then never uses a ferry, and waypoints never snap onto one; if no route exists without a ferry, the request fails.
      - `useFerry` number, double, nullable: Preference for ferries, from `0` (avoid when possible) to `1` (prefer). A preference only: a ferry is still used when there is no reasonable alternative. Defaults to `0.5`.
  - `directionsOptions` DirectionsOptions
    - `language` string, nullable: Language for narrative directions.
  - `locations` RouteLocation[], required: Two or more ordered waypoints. The first is the origin, the last is the destination.
    - `lat` number, double, required
    - `lon` number, double, required
    - `radius` number, double, nullable: Meters around the waypoint in which every road or path is considered as a snapping candidate, not only the closest. This is not a limit — use `searchCutoff` for that. Defaults to 0.
    - `searchCutoff` number, double, nullable: Maximum snapping distance in meters. If no usable road or path lies within this distance, the request fails with `400` (error code 171) instead of snapping further away. Use it to enforce a strict snapping limit. Defaults to 35,000.
    - `type` 'break' | 'break_through': `break` (default): a stop that ends one leg and starts the next. The incoming and outgoing legs each snap to the waypoint on their own, so where several roads lie equally close (a dual carriageway, a bridge with a cycle track) they can end and start a few meters apart, and the route may turn around at the stop. `break_through`: also a stop with separate legs, but the outgoing leg continues from exactly where the incoming leg arrived, so the legs always connect. Turning around at the stop is not allowed; if continuing is impossible (a dead end), the request fails with no route found. Use it on stops the route passes through, and keep `break` where turning around is expected.
  - `units` 'kilometers' | 'miles'

## Response `200`

Route response.

- RouteResponse: Route response. The interesting fields are `trip.summary` (totals) and `trip.legs[i].shape` (an encoded polyline ready to render).
  - `trip` Trip, required
    - `language` string, required
    - `legs` RouteLeg[], required
      - `maneuvers` RouteManeuver[], required
        - `beginShapeIndex` integer, required
        - `endShapeIndex` integer, required
        - `instruction` string, required
        - `length` number, double, required
        - `time` number, double, required
      - `shape` string, required: Encoded polyline at 1e-6 precision (the standard Google polyline algorithm with 6 decimals instead of 5). Decoders are available for every major language — in JavaScript, `@mapbox/polyline` with the precision set to 6 returns `[lat, lon]` pairs.
      - `summary` RouteSummary, required
        - `length` number, double, required: Total length in the requested units.
        - `maxLat` number, double, nullable
        - `maxLon` number, double, nullable
        - `minLat` number, double, nullable
        - `minLon` number, double, nullable
        - `time` number, double, required: Total travel time in seconds.
    - `status` integer, required
    - `statusMessage` string, required
    - `summary` RouteSummary, required
      - `length` number, double, required: Total length in the requested units.
      - `maxLat` number, double, nullable
      - `maxLon` number, double, nullable
      - `minLat` number, double, nullable
      - `minLon` number, double, nullable
      - `time` number, double, required: Total travel time in seconds.
    - `units` string, required

## Other responses

- `400`: Malformed body or unsupported costing profile.
- `401`: Missing, malformed, or revoked API key.
- `429`: Monthly quota exhausted.

---

[API](https://skmtc.dev/rijwind/apis/rijwind-api.md) · [All operations](https://skmtc.dev/rijwind/apis/rijwind-api/llms.txt) · [OpenAPI document](https://skmtc.dev/rijwind/apis/rijwind-api/revisions/01d72fb6aa4d?raw)