Directions API

Overview

POST /directions plans a route from an origin to a destination, optionally through waypoints. It is self-hosted over GB data — road routing by car/bike/foot, and public transport (GB National Rail + London bus/tube/DLR/ferry). Responses are engine-normalised, so the shape is stable regardless of which engine served the request.

Authenticate with a key scoped to "directions" — send it as an x-api-key header, or ?key= for browser (publishable) keys locked to your origins. Each call is metered.

Request

Points accept [lon, lat] arrays or {lat, lon} / {lat, lng} objects — so you can chain straight off /predict.

curl -X POST "https://api.goggleplaces.com/directions" \
  -H "x-api-key: gk_live_sk_..." \
  -H "content-type: application/json" \
  -d '{
    "origin": [-2.2426, 53.4808],
    "destination": [-1.8904, 52.4862],
    "mode": "auto",
    "alternatives": true
  }'

Parameters

origin, destination — required. waypoints[] — up to 25 intermediate stops. mode — auto | bicycle | pedestrian | transit (aliases: drive/car, bike/cycling, walk/foot, bus/rail). alternatives — return alternate routes (2-point road routes only). optimize — reorder waypoints to minimise total time (TSP). overview — "full" | "simplified".

Response

routes[] ordered fastest-first. Each route has distance_m, duration_s, a GeoJSON LineString geometry, and legs[] (one per waypoint span; for transit, one per walk/vehicle leg with its mode, route name, board/alight stops and times). Road legs also carry steps[] — every road on the route with its name, distance_m and duration_s — for a turn-by-turn breakdown.

{
  "mode": "auto",
  "engine": "valhalla",
  "routes": [
    {
      "distance_m": 141000,
      "duration_s": 6120,
      "geometry": { "type": "LineString", "coordinates": [[-2.2426,53.4808], ...] },
      "legs": [ { "distance_m": 141000, "duration_s": 6120, "steps": [ ... ] } ]
    }
  ]
}

Public transport

Set mode=transit for a walk → bus/train → walk journey. Each leg carries mode (WALK/BUS/RAIL/SUBWAY/TRAM/FERRY), the service route name, from/to stops and start_time/end_time from the live timetable. When an end isn’t beside a station, the journey is stitched drive → rail → drive — a road hop to the nearest station, the train, then a road hop to the destination — so rail routing works right across Great Britain; those road hops arrive as CAR legs. Coverage is GB National Rail plus London local transport.

curl -X POST "https://api.goggleplaces.com/directions" \
  -H "x-api-key: gk_live_sk_..." \
  -H "content-type: application/json" \
  -d '{ "origin": [-2.2309, 53.4774], "destination": [-1.8990, 52.4778], "mode": "transit" }'

Convenience GET

For a simple two-point route you can use GET with lat,lon pairs.

curl "https://api.goggleplaces.com/directions?from=53.4808,-2.2426&to=52.4862,-1.8904" \
  -H "x-api-key: gk_live_sk_..."

Share a route

Turn any route into shareable links — a reopen link, Google/Apple/Waze deep-links (which show on CarPlay and Android Auto in the car), and a GPX file — or text it to a phone with POST /share.