# Routing

## Calculate a route between two points

`$ plaza routing route`

**post** `/api/v1/route`

Calculate a route between two points

### Parameters

- `--destination: object { lat, lng }`

  Geographic coordinate as a JSON object with `lat` and `lng` fields.

- `--origin: object { lat, lng }`

  Geographic coordinate as a JSON object with `lat` and `lng` fields.

- `--alternatives: optional number`

  Number of alternative routes to return (0-3, default 0). When > 0, response is a FeatureCollection of route Features.

- `--annotations: optional boolean`

  Include per-edge annotations (speed, duration) on the route (default: false)

- `--depart-at: optional string`

  Departure time for traffic-aware routing (ISO 8601)

- `--ev: optional object { battery_capacity_wh, connector_types, initial_charge_pct, 2 more }`

  Electric vehicle parameters for EV-aware routing

- `--exclude: optional string`

  Comma-separated road types to exclude (e.g. `toll,motorway,ferry`)

- `--geometries: optional "geojson" or "polyline" or "polyline6"`

  Geometry encoding format. Default: `geojson`.

- `--mode: optional "auto" or "foot" or "bicycle"`

  Travel mode (default: `auto`)

- `--overview: optional "full" or "simplified" or "false"`

  Level of geometry detail: `full` (all points), `simplified` (Douglas-Peucker), `false` (no geometry). Default: `full`.

- `--steps: optional boolean`

  Include turn-by-turn navigation steps (default: false)

- `--traffic-model: optional "best_guess" or "optimistic" or "pessimistic"`

  Traffic prediction model (only used when `depart_at` is set)

- `--waypoint: optional array of object { lat, lng }`

  Intermediate waypoints to visit in order (maximum 25)

### Returns

- `route_result: object { geometry, properties, type }`

  GeoJSON Feature representing a calculated route. The geometry is a LineString or MultiLineString of the route path. When `alternatives > 0`, the response is a FeatureCollection containing multiple route Features.

  - `geometry: object { coordinates, type }`

    GeoJSON Geometry object per RFC 7946. Coordinates use [longitude, latitude] order. 3D coordinates [lng, lat, elevation] are used for elevation endpoints.

    - `coordinates: array of number or array of array of number or array of array of array of number or array of array of array of array of number`

      Coordinates array. Nesting depth varies by geometry type: Point = [lng, lat], LineString = [[lng, lat], ...], Polygon = [[[lng, lat], ...], ...], etc.

      - `Point: array of number`

        [longitude, latitude] or [longitude, latitude, elevation]

      - `LineString or MultiPoint: array of array of number`

        Array of [lng, lat] positions

      - `Polygon or MultiLineString: array of array of array of number`

        Array of linear rings / line strings

      - `MultiPolygon: array of array of array of array of number`

        Array of polygons

    - `type: "Point" or "LineString" or "Polygon" or 3 more`

      Geometry type

      - `"Point"`

      - `"LineString"`

      - `"Polygon"`

      - `"MultiPoint"`

      - `"MultiLineString"`

      - `"MultiPolygon"`

  - `properties: object { distance_m, duration_s, annotations, 4 more }`

    Route metadata

    - `distance_m: number`

      Total route distance in meters

    - `duration_s: number`

      Estimated travel duration in seconds

    - `annotations: optional map[unknown]`

      Per-edge annotations (present when `annotations: true` in request)

    - `charge_profile: optional array of array of number`

      Battery charge level at route waypoints as [distance_fraction, charge_pct] pairs (EV routes only)

    - `charging_stops: optional array of map[unknown]`

      Recommended charging stops along the route (EV routes only)

    - `edges: optional array of map[unknown]`

      Edge-level route details (present when `annotations: true`)

    - `energy_used_wh: optional number`

      Total energy consumed in watt-hours (EV routes only)

  - `type: "Feature"`

    - `"Feature"`

### Example

```cli
plaza routing route \
  --api-key 'My API Key' \
  --destination '{lat: 48.8584, lng: 2.2945}' \
  --origin '{lat: 48.8566, lng: 2.3522}'
```

#### Response

```json
{
  "geometry": {
    "coordinates": [
      2.3522,
      48.8566
    ],
    "type": "Point"
  },
  "properties": {
    "distance_m": 4523.7,
    "duration_s": 847.2,
    "annotations": {
      "foo": "bar"
    },
    "charge_profile": [
      [
        0
      ]
    ],
    "charging_stops": [
      {
        "foo": "bar"
      }
    ],
    "edges": [
      {
        "foo": "bar"
      }
    ],
    "energy_used_wh": 0
  },
  "type": "Feature"
}
```

## Snap a coordinate to the nearest road

`$ plaza routing nearest`

**get** `/api/v1/nearest`

Snap a coordinate to the nearest road

### Parameters

- `--lat: number`

  Latitude

- `--lng: number`

  Longitude

- `--output-fields: optional string`

  Comma-separated property fields to include

- `--output-include: optional string`

  Extra computed fields: bbox, distance, center

- `--output-precision: optional number`

  Coordinate decimal precision (1-15, default 7)

- `--radius: optional number`

  Search radius in meters (default 500, max 5000)

### Returns

- `nearest_result: object { geometry, properties, type }`

  GeoJSON Point Feature representing the nearest point on the road network to the input coordinate. Used for snapping GPS coordinates to roads.

  - `geometry: object { coordinates, type }`

    GeoJSON Geometry object per RFC 7946. Coordinates use [longitude, latitude] order. 3D coordinates [lng, lat, elevation] are used for elevation endpoints.

    - `coordinates: array of number or array of array of number or array of array of array of number or array of array of array of array of number`

      Coordinates array. Nesting depth varies by geometry type: Point = [lng, lat], LineString = [[lng, lat], ...], Polygon = [[[lng, lat], ...], ...], etc.

      - `Point: array of number`

        [longitude, latitude] or [longitude, latitude, elevation]

      - `LineString or MultiPoint: array of array of number`

        Array of [lng, lat] positions

      - `Polygon or MultiLineString: array of array of array of number`

        Array of linear rings / line strings

      - `MultiPolygon: array of array of array of array of number`

        Array of polygons

    - `type: "Point" or "LineString" or "Polygon" or 3 more`

      Geometry type

      - `"Point"`

      - `"LineString"`

      - `"Polygon"`

      - `"MultiPoint"`

      - `"MultiLineString"`

      - `"MultiPolygon"`

  - `properties: object { distance_m, edge_id, edge_length_m, 3 more }`

    Snap result metadata

    - `distance_m: optional number`

      Distance from the input coordinate to the snapped point in meters

    - `edge_id: optional number`

      ID of the road network edge that was snapped to

    - `edge_length_m: optional number`

      Length of the matched road edge in meters

    - `highway: optional string`

      OSM highway tag value (e.g. `residential`, `primary`, `motorway`)

    - `osm_way_id: optional number`

      OSM way ID of the matched road segment

    - `surface: optional string`

      OSM surface tag value (e.g. `asphalt`, `gravel`, `paved`)

  - `type: "Feature"`

    - `"Feature"`

### Example

```cli
plaza routing nearest \
  --api-key 'My API Key' \
  --lat 0 \
  --lng 0
```

#### Response

```json
{
  "geometry": {
    "coordinates": [
      2.3522,
      48.8566
    ],
    "type": "Point"
  },
  "properties": {
    "distance_m": 12.4,
    "edge_id": 0,
    "edge_length_m": 0,
    "highway": "highway",
    "osm_way_id": 0,
    "surface": "surface"
  },
  "type": "Feature"
}
```

## Snap a coordinate to the nearest road

`$ plaza routing nearest-post`

**post** `/api/v1/nearest`

Snap a coordinate to the nearest road

### Parameters

- `--lat: number`

  Latitude

- `--lng: number`

  Longitude

- `--output-fields: optional string`

  Comma-separated property fields to include

- `--output-include: optional string`

  Extra computed fields: bbox, distance, center

- `--output-precision: optional number`

  Coordinate decimal precision (1-15, default 7)

- `--radius: optional number`

  Search radius in meters (default 500, max 5000)

### Returns

- `nearest_result: object { geometry, properties, type }`

  GeoJSON Point Feature representing the nearest point on the road network to the input coordinate. Used for snapping GPS coordinates to roads.

  - `geometry: object { coordinates, type }`

    GeoJSON Geometry object per RFC 7946. Coordinates use [longitude, latitude] order. 3D coordinates [lng, lat, elevation] are used for elevation endpoints.

    - `coordinates: array of number or array of array of number or array of array of array of number or array of array of array of array of number`

      Coordinates array. Nesting depth varies by geometry type: Point = [lng, lat], LineString = [[lng, lat], ...], Polygon = [[[lng, lat], ...], ...], etc.

      - `Point: array of number`

        [longitude, latitude] or [longitude, latitude, elevation]

      - `LineString or MultiPoint: array of array of number`

        Array of [lng, lat] positions

      - `Polygon or MultiLineString: array of array of array of number`

        Array of linear rings / line strings

      - `MultiPolygon: array of array of array of array of number`

        Array of polygons

    - `type: "Point" or "LineString" or "Polygon" or 3 more`

      Geometry type

      - `"Point"`

      - `"LineString"`

      - `"Polygon"`

      - `"MultiPoint"`

      - `"MultiLineString"`

      - `"MultiPolygon"`

  - `properties: object { distance_m, edge_id, edge_length_m, 3 more }`

    Snap result metadata

    - `distance_m: optional number`

      Distance from the input coordinate to the snapped point in meters

    - `edge_id: optional number`

      ID of the road network edge that was snapped to

    - `edge_length_m: optional number`

      Length of the matched road edge in meters

    - `highway: optional string`

      OSM highway tag value (e.g. `residential`, `primary`, `motorway`)

    - `osm_way_id: optional number`

      OSM way ID of the matched road segment

    - `surface: optional string`

      OSM surface tag value (e.g. `asphalt`, `gravel`, `paved`)

  - `type: "Feature"`

    - `"Feature"`

### Example

```cli
plaza routing nearest-post \
  --api-key 'My API Key' \
  --lat 0 \
  --lng 0
```

#### Response

```json
{
  "geometry": {
    "coordinates": [
      2.3522,
      48.8566
    ],
    "type": "Point"
  },
  "properties": {
    "distance_m": 12.4,
    "edge_id": 0,
    "edge_length_m": 0,
    "highway": "highway",
    "osm_way_id": 0,
    "surface": "surface"
  },
  "type": "Feature"
}
```

## Calculate an isochrone from a point

`$ plaza routing isochrone`

**get** `/api/v1/isochrone`

Calculate an isochrone from a point

### Parameters

- `--lat: number`

  Latitude

- `--lng: number`

  Longitude

- `--time: number`

  Travel time in seconds (1-7200)

- `--mode: optional string`

  Travel mode (auto, foot, bicycle)

- `--output-fields: optional string`

  Comma-separated property fields to include

- `--output-geometry: optional boolean`

  Include geometry (default true)

- `--output-include: optional string`

  Extra computed fields: bbox, center

- `--output-precision: optional number`

  Coordinate decimal precision (1-15, default 7)

- `--output-simplify: optional number`

  Simplify geometry tolerance in meters

### Returns

- `RoutingIsochroneResponse: object { features, geometry, properties, type }`

  GeoJSON Feature or FeatureCollection representing isochrone polygons — areas reachable within the specified travel time(s). Single time value returns a Feature; comma-separated times return a FeatureCollection with one polygon per contour.

  - `features: optional array of GeoJsonFeature`

    Array of isochrone polygon Features (multi-contour only)

    - `geometry: object { coordinates, type }`

      GeoJSON Geometry object per RFC 7946. Coordinates use [longitude, latitude] order. 3D coordinates [lng, lat, elevation] are used for elevation endpoints.

      - `coordinates: array of number or array of array of number or array of array of array of number or array of array of array of array of number`

        Coordinates array. Nesting depth varies by geometry type: Point = [lng, lat], LineString = [[lng, lat], ...], Polygon = [[[lng, lat], ...], ...], etc.

        - `Point: array of number`

          [longitude, latitude] or [longitude, latitude, elevation]

        - `LineString or MultiPoint: array of array of number`

          Array of [lng, lat] positions

        - `Polygon or MultiLineString: array of array of array of number`

          Array of linear rings / line strings

        - `MultiPolygon: array of array of array of array of number`

          Array of polygons

      - `type: "Point" or "LineString" or "Polygon" or 3 more`

        Geometry type

        - `"Point"`

        - `"LineString"`

        - `"Polygon"`

        - `"MultiPoint"`

        - `"MultiLineString"`

        - `"MultiPolygon"`

    - `properties: map[unknown]`

      OSM tags flattened as key-value pairs, plus `@type` (node/way/relation) and `@id` (OSM ID) metadata fields. May include `distance_m` for proximity queries.

    - `type: "Feature"`

      Always `Feature`

      - `"Feature"`

    - `id: optional string`

      Compound identifier in `type/osm_id` format

  - `geometry: optional object { coordinates, type }`

    GeoJSON Geometry object per RFC 7946. Coordinates use [longitude, latitude] order. 3D coordinates [lng, lat, elevation] are used for elevation endpoints.

    - `coordinates: array of number or array of array of number or array of array of array of number or array of array of array of array of number`

      Coordinates array. Nesting depth varies by geometry type: Point = [lng, lat], LineString = [[lng, lat], ...], Polygon = [[[lng, lat], ...], ...], etc.

    - `type: "Point" or "LineString" or "Polygon" or 3 more`

      Geometry type

  - `properties: optional object { area_m2, max_cost_s, mode, 2 more }`

    Isochrone metadata

    - `area_m2: optional number`

      Area of the isochrone polygon in square meters (multi-contour features only)

    - `max_cost_s: optional number`

      Maximum actual travel cost in seconds to the isochrone boundary (single contour only)

    - `mode: optional "auto" or "foot" or "bicycle"`

      Travel mode used for the isochrone calculation

      - `"auto"`

      - `"foot"`

      - `"bicycle"`

    - `time_seconds: optional number`

      Travel time budget in seconds

    - `vertices_reached: optional number`

      Number of road network vertices within the isochrone

  - `type: optional "Feature" or "FeatureCollection"`

    `Feature` for single contour, `FeatureCollection` for multiple contours

    - `"Feature"`

    - `"FeatureCollection"`

### Example

```cli
plaza routing isochrone \
  --api-key 'My API Key' \
  --lat 0 \
  --lng 0 \
  --time 0
```

#### Response

```json
{
  "features": [
    {
      "geometry": {
        "coordinates": [
          2.3522,
          48.8566
        ],
        "type": "Point"
      },
      "properties": {
        "@id": "bar",
        "@type": "bar",
        "amenity": "bar",
        "cuisine": "bar",
        "name": "bar"
      },
      "type": "Feature",
      "id": "node/21154906"
    }
  ],
  "geometry": {
    "coordinates": [
      2.3522,
      48.8566
    ],
    "type": "Point"
  },
  "properties": {
    "area_m2": 0,
    "max_cost_s": 0,
    "mode": "auto",
    "time_seconds": 0,
    "vertices_reached": 0
  },
  "type": "Feature"
}
```

## Calculate an isochrone from a point

`$ plaza routing isochrone-post`

**post** `/api/v1/isochrone`

Calculate an isochrone from a point

### Parameters

- `--lat: number`

  Latitude

- `--lng: number`

  Longitude

- `--time: number`

  Travel time in seconds (1-7200)

- `--mode: optional string`

  Travel mode (auto, foot, bicycle)

- `--output-fields: optional string`

  Comma-separated property fields to include

- `--output-geometry: optional boolean`

  Include geometry (default true)

- `--output-include: optional string`

  Extra computed fields: bbox, center

- `--output-precision: optional number`

  Coordinate decimal precision (1-15, default 7)

- `--output-simplify: optional number`

  Simplify geometry tolerance in meters

### Returns

- `RoutingIsochronePostResponse: object { features, geometry, properties, type }`

  GeoJSON Feature or FeatureCollection representing isochrone polygons — areas reachable within the specified travel time(s). Single time value returns a Feature; comma-separated times return a FeatureCollection with one polygon per contour.

  - `features: optional array of GeoJsonFeature`

    Array of isochrone polygon Features (multi-contour only)

    - `geometry: object { coordinates, type }`

      GeoJSON Geometry object per RFC 7946. Coordinates use [longitude, latitude] order. 3D coordinates [lng, lat, elevation] are used for elevation endpoints.

      - `coordinates: array of number or array of array of number or array of array of array of number or array of array of array of array of number`

        Coordinates array. Nesting depth varies by geometry type: Point = [lng, lat], LineString = [[lng, lat], ...], Polygon = [[[lng, lat], ...], ...], etc.

        - `Point: array of number`

          [longitude, latitude] or [longitude, latitude, elevation]

        - `LineString or MultiPoint: array of array of number`

          Array of [lng, lat] positions

        - `Polygon or MultiLineString: array of array of array of number`

          Array of linear rings / line strings

        - `MultiPolygon: array of array of array of array of number`

          Array of polygons

      - `type: "Point" or "LineString" or "Polygon" or 3 more`

        Geometry type

        - `"Point"`

        - `"LineString"`

        - `"Polygon"`

        - `"MultiPoint"`

        - `"MultiLineString"`

        - `"MultiPolygon"`

    - `properties: map[unknown]`

      OSM tags flattened as key-value pairs, plus `@type` (node/way/relation) and `@id` (OSM ID) metadata fields. May include `distance_m` for proximity queries.

    - `type: "Feature"`

      Always `Feature`

      - `"Feature"`

    - `id: optional string`

      Compound identifier in `type/osm_id` format

  - `geometry: optional object { coordinates, type }`

    GeoJSON Geometry object per RFC 7946. Coordinates use [longitude, latitude] order. 3D coordinates [lng, lat, elevation] are used for elevation endpoints.

    - `coordinates: array of number or array of array of number or array of array of array of number or array of array of array of array of number`

      Coordinates array. Nesting depth varies by geometry type: Point = [lng, lat], LineString = [[lng, lat], ...], Polygon = [[[lng, lat], ...], ...], etc.

    - `type: "Point" or "LineString" or "Polygon" or 3 more`

      Geometry type

  - `properties: optional object { area_m2, max_cost_s, mode, 2 more }`

    Isochrone metadata

    - `area_m2: optional number`

      Area of the isochrone polygon in square meters (multi-contour features only)

    - `max_cost_s: optional number`

      Maximum actual travel cost in seconds to the isochrone boundary (single contour only)

    - `mode: optional "auto" or "foot" or "bicycle"`

      Travel mode used for the isochrone calculation

      - `"auto"`

      - `"foot"`

      - `"bicycle"`

    - `time_seconds: optional number`

      Travel time budget in seconds

    - `vertices_reached: optional number`

      Number of road network vertices within the isochrone

  - `type: optional "Feature" or "FeatureCollection"`

    `Feature` for single contour, `FeatureCollection` for multiple contours

    - `"Feature"`

    - `"FeatureCollection"`

### Example

```cli
plaza routing isochrone-post \
  --api-key 'My API Key' \
  --lat 0 \
  --lng 0 \
  --time 0
```

#### Response

```json
{
  "features": [
    {
      "geometry": {
        "coordinates": [
          2.3522,
          48.8566
        ],
        "type": "Point"
      },
      "properties": {
        "@id": "bar",
        "@type": "bar",
        "amenity": "bar",
        "cuisine": "bar",
        "name": "bar"
      },
      "type": "Feature",
      "id": "node/21154906"
    }
  ],
  "geometry": {
    "coordinates": [
      2.3522,
      48.8566
    ],
    "type": "Point"
  },
  "properties": {
    "area_m2": 0,
    "max_cost_s": 0,
    "mode": "auto",
    "time_seconds": 0,
    "vertices_reached": 0
  },
  "type": "Feature"
}
```

## Calculate a distance matrix between points

`$ plaza routing matrix`

**post** `/api/v1/matrix`

Calculate a distance matrix between points

### Parameters

- `--destination: array of object { lat, lng }`

  Array of destination coordinates (max 50)

- `--origin: array of object { lat, lng }`

  Array of origin coordinates (max 50)

- `--annotations: optional string`

  Comma-separated list of annotations to include: `duration` (always included), `distance`. Example: `duration,distance`.

- `--fallback-speed: optional number`

  Fallback speed in km/h for pairs where no route exists. When set, unreachable pairs get estimated values instead of null.

- `--mode: optional "auto" or "foot" or "bicycle"`

  Travel mode (default: `auto`)

### Returns

- `matrix_result: map[unknown]`

  Distance matrix result. The exact response shape depends on the routing backend. Contains duration (and optionally distance) data for all origin-destination pairs. Null values indicate unreachable pairs.

### Example

```cli
plaza routing matrix \
  --api-key 'My API Key' \
  --destination '{lat: 48.8584, lng: 2.2945}' \
  --origin '{lat: 48.8566, lng: 2.3522}' \
  --origin '{lat: 48.8606, lng: 2.3376}'
```

#### Response

```json
{
  "foo": "bar"
}
```

## Domain Types

### Matrix Request

- `matrix_request: object { destinations, origins, annotations, 2 more }`

  Request body for distance matrix calculation. Computes travel durations (and optionally distances) between every origin-destination pair. Maximum 2,500 pairs (origins × destinations), each list capped at 50 coordinates.

  - `destinations: array of object { lat, lng }`

    Array of destination coordinates (max 50)

    - `lat: number`

      Latitude in decimal degrees (-90 to 90)

    - `lng: number`

      Longitude in decimal degrees (-180 to 180)

  - `origins: array of object { lat, lng }`

    Array of origin coordinates (max 50)

    - `lat: number`

      Latitude in decimal degrees (-90 to 90)

    - `lng: number`

      Longitude in decimal degrees (-180 to 180)

  - `annotations: optional string`

    Comma-separated list of annotations to include: `duration` (always included), `distance`. Example: `duration,distance`.

  - `fallback_speed: optional number`

    Fallback speed in km/h for pairs where no route exists. When set, unreachable pairs get estimated values instead of null.

  - `mode: optional "auto" or "foot" or "bicycle"`

    Travel mode (default: `auto`)

    - `"auto"`

    - `"foot"`

    - `"bicycle"`

### Matrix Result

- `matrix_result: map[unknown]`

  Distance matrix result. The exact response shape depends on the routing backend. Contains duration (and optionally distance) data for all origin-destination pairs. Null values indicate unreachable pairs.

### Nearest Result

- `nearest_result: object { geometry, properties, type }`

  GeoJSON Point Feature representing the nearest point on the road network to the input coordinate. Used for snapping GPS coordinates to roads.

  - `geometry: object { coordinates, type }`

    GeoJSON Geometry object per RFC 7946. Coordinates use [longitude, latitude] order. 3D coordinates [lng, lat, elevation] are used for elevation endpoints.

    - `coordinates: array of number or array of array of number or array of array of array of number or array of array of array of array of number`

      Coordinates array. Nesting depth varies by geometry type: Point = [lng, lat], LineString = [[lng, lat], ...], Polygon = [[[lng, lat], ...], ...], etc.

      - `Point: array of number`

        [longitude, latitude] or [longitude, latitude, elevation]

      - `LineString or MultiPoint: array of array of number`

        Array of [lng, lat] positions

      - `Polygon or MultiLineString: array of array of array of number`

        Array of linear rings / line strings

      - `MultiPolygon: array of array of array of array of number`

        Array of polygons

    - `type: "Point" or "LineString" or "Polygon" or 3 more`

      Geometry type

      - `"Point"`

      - `"LineString"`

      - `"Polygon"`

      - `"MultiPoint"`

      - `"MultiLineString"`

      - `"MultiPolygon"`

  - `properties: object { distance_m, edge_id, edge_length_m, 3 more }`

    Snap result metadata

    - `distance_m: optional number`

      Distance from the input coordinate to the snapped point in meters

    - `edge_id: optional number`

      ID of the road network edge that was snapped to

    - `edge_length_m: optional number`

      Length of the matched road edge in meters

    - `highway: optional string`

      OSM highway tag value (e.g. `residential`, `primary`, `motorway`)

    - `osm_way_id: optional number`

      OSM way ID of the matched road segment

    - `surface: optional string`

      OSM surface tag value (e.g. `asphalt`, `gravel`, `paved`)

  - `type: "Feature"`

    - `"Feature"`

### Route Request

- `route_request: object { destination, origin, alternatives, 10 more }`

  Request body for route calculation. Origin and destination are lat/lng coordinate objects. Supports optional waypoints, alternative routes, turn-by-turn steps, and EV routing parameters.

  - `destination: object { lat, lng }`

    Geographic coordinate as a JSON object with `lat` and `lng` fields.

    - `lat: number`

      Latitude in decimal degrees (-90 to 90)

    - `lng: number`

      Longitude in decimal degrees (-180 to 180)

  - `origin: object { lat, lng }`

    Geographic coordinate as a JSON object with `lat` and `lng` fields.

    - `lat: number`

      Latitude in decimal degrees (-90 to 90)

    - `lng: number`

      Longitude in decimal degrees (-180 to 180)

  - `alternatives: optional number`

    Number of alternative routes to return (0-3, default 0). When > 0, response is a FeatureCollection of route Features.

  - `annotations: optional boolean`

    Include per-edge annotations (speed, duration) on the route (default: false)

  - `depart_at: optional string`

    Departure time for traffic-aware routing (ISO 8601)

  - `ev: optional object { battery_capacity_wh, connector_types, initial_charge_pct, 2 more }`

    Electric vehicle parameters for EV-aware routing

    - `battery_capacity_wh: number`

      Total battery capacity in watt-hours (required for EV routing)

    - `connector_types: optional array of string`

      Acceptable connector types (e.g. `["ccs", "chademo"]`)

    - `initial_charge_pct: optional number`

      Starting charge as a fraction 0-1 (default: 0.8)

    - `min_charge_pct: optional number`

      Minimum acceptable charge at destination as a fraction 0-1 (default: 0.10)

    - `min_power_kw: optional number`

      Minimum charger power in kilowatts

  - `exclude: optional string`

    Comma-separated road types to exclude (e.g. `toll,motorway,ferry`)

  - `geometries: optional "geojson" or "polyline" or "polyline6"`

    Geometry encoding format. Default: `geojson`.

    - `"geojson"`

    - `"polyline"`

    - `"polyline6"`

  - `mode: optional "auto" or "foot" or "bicycle"`

    Travel mode (default: `auto`)

    - `"auto"`

    - `"foot"`

    - `"bicycle"`

  - `overview: optional "full" or "simplified" or "false"`

    Level of geometry detail: `full` (all points), `simplified` (Douglas-Peucker), `false` (no geometry). Default: `full`.

    - `"full"`

    - `"simplified"`

    - `"false"`

  - `steps: optional boolean`

    Include turn-by-turn navigation steps (default: false)

  - `traffic_model: optional "best_guess" or "optimistic" or "pessimistic"`

    Traffic prediction model (only used when `depart_at` is set)

    - `"best_guess"`

    - `"optimistic"`

    - `"pessimistic"`

  - `waypoints: optional array of object { lat, lng }`

    Intermediate waypoints to visit in order (maximum 25)

    - `lat: number`

      Latitude in decimal degrees (-90 to 90)

    - `lng: number`

      Longitude in decimal degrees (-180 to 180)

### Route Result

- `route_result: object { geometry, properties, type }`

  GeoJSON Feature representing a calculated route. The geometry is a LineString or MultiLineString of the route path. When `alternatives > 0`, the response is a FeatureCollection containing multiple route Features.

  - `geometry: object { coordinates, type }`

    GeoJSON Geometry object per RFC 7946. Coordinates use [longitude, latitude] order. 3D coordinates [lng, lat, elevation] are used for elevation endpoints.

    - `coordinates: array of number or array of array of number or array of array of array of number or array of array of array of array of number`

      Coordinates array. Nesting depth varies by geometry type: Point = [lng, lat], LineString = [[lng, lat], ...], Polygon = [[[lng, lat], ...], ...], etc.

      - `Point: array of number`

        [longitude, latitude] or [longitude, latitude, elevation]

      - `LineString or MultiPoint: array of array of number`

        Array of [lng, lat] positions

      - `Polygon or MultiLineString: array of array of array of number`

        Array of linear rings / line strings

      - `MultiPolygon: array of array of array of array of number`

        Array of polygons

    - `type: "Point" or "LineString" or "Polygon" or 3 more`

      Geometry type

      - `"Point"`

      - `"LineString"`

      - `"Polygon"`

      - `"MultiPoint"`

      - `"MultiLineString"`

      - `"MultiPolygon"`

  - `properties: object { distance_m, duration_s, annotations, 4 more }`

    Route metadata

    - `distance_m: number`

      Total route distance in meters

    - `duration_s: number`

      Estimated travel duration in seconds

    - `annotations: optional map[unknown]`

      Per-edge annotations (present when `annotations: true` in request)

    - `charge_profile: optional array of array of number`

      Battery charge level at route waypoints as [distance_fraction, charge_pct] pairs (EV routes only)

    - `charging_stops: optional array of map[unknown]`

      Recommended charging stops along the route (EV routes only)

    - `edges: optional array of map[unknown]`

      Edge-level route details (present when `annotations: true`)

    - `energy_used_wh: optional number`

      Total energy consumed in watt-hours (EV routes only)

  - `type: "Feature"`

    - `"Feature"`