# Routing

## Calculate a route between two points

`routing.route(**kwargs) -> RouteResult`

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

Calculate a route between two points

### Parameters

- `destination: { lat, lng}`

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

  - `lat: Float`

    Latitude in decimal degrees (-90 to 90)

  - `lng: Float`

    Longitude in decimal degrees (-180 to 180)

- `origin: { lat, lng}`

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

  - `lat: Float`

    Latitude in decimal degrees (-90 to 90)

  - `lng: Float`

    Longitude in decimal degrees (-180 to 180)

- `alternatives: Integer`

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

- `annotations: bool`

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

- `depart_at: Time`

  Departure time for traffic-aware routing (ISO 8601)

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

  Electric vehicle parameters for EV-aware routing

  - `battery_capacity_wh: Float`

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

  - `connector_types: Array[String]`

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

  - `initial_charge_pct: Float`

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

  - `min_charge_pct: Float`

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

  - `min_power_kw: Float`

    Minimum charger power in kilowatts

- `exclude: String`

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

- `geometries: :geojson | :polyline | :polyline6`

  Geometry encoding format. Default: `geojson`.

  - `:geojson`

  - `:polyline`

  - `:polyline6`

- `mode: :auto | :foot | :bicycle`

  Travel mode (default: `auto`)

  - `:auto`

  - `:foot`

  - `:bicycle`

- `overview: :full | :simplified | :false`

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

  - `:full`

  - `:simplified`

  - `:false`

- `steps: bool`

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

- `traffic_model: :best_guess | :optimistic | :pessimistic`

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

  - `:best_guess`

  - `:optimistic`

  - `:pessimistic`

- `waypoints: Array[{ lat, lng}]`

  Intermediate waypoints to visit in order (maximum 25)

  - `lat: Float`

    Latitude in decimal degrees (-90 to 90)

  - `lng: Float`

    Longitude in decimal degrees (-180 to 180)

### Returns

- `class RouteResult`

  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: GeoJsonGeometry`

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

    - `coordinates: Array[Float] | Array[Array[Float]] | Array[Array[Array[Float]]] | Array[Array[Array[Array[Float]]]]`

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

      - `Array[Float]`

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

      - `Array[Array[Float]]`

        Array of [lng, lat] positions

      - `Array[Array[Array[Float]]]`

        Array of linear rings / line strings

      - `Array[Array[Array[Array[Float]]]]`

        Array of polygons

    - `type: :Point | :LineString | :Polygon | 3 more`

      Geometry type

      - `:Point`

      - `:LineString`

      - `:Polygon`

      - `:MultiPoint`

      - `:MultiLineString`

      - `:MultiPolygon`

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

    Route metadata

    - `distance_m: Float`

      Total route distance in meters

    - `duration_s: Float`

      Estimated travel duration in seconds

    - `annotations: Hash[Symbol, untyped]`

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

    - `charge_profile: Array[Array[Float]]`

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

    - `charging_stops: Array[Hash[Symbol, untyped]]`

      Recommended charging stops along the route (EV routes only)

    - `edges: Array[Hash[Symbol, untyped]]`

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

    - `energy_used_wh: Float`

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

  - `type: :Feature`

    - `:Feature`

### Example

```ruby
require "plaza"

plaza = Plaza::Client.new(
  api_key: "My API Key",
  environment: "local" # defaults to "production"
)

route_result = plaza.routing.route(destination: {lat: 48.8584, lng: 2.2945}, origin: {lat: 48.8566, lng: 2.3522})

puts(route_result)
```

#### 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

`routing.nearest(**kwargs) -> NearestResult`

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

Snap a coordinate to the nearest road

### Parameters

- `lat: Float`

  Latitude

- `lng: Float`

  Longitude

- `output_fields: String`

  Comma-separated property fields to include

- `output_include: String`

  Extra computed fields: bbox, distance, center

- `output_precision: Integer`

  Coordinate decimal precision (1-15, default 7)

- `radius: Integer`

  Search radius in meters (default 500, max 5000)

### Returns

- `class NearestResult`

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

  - `geometry: GeoJsonGeometry`

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

    - `coordinates: Array[Float] | Array[Array[Float]] | Array[Array[Array[Float]]] | Array[Array[Array[Array[Float]]]]`

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

      - `Array[Float]`

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

      - `Array[Array[Float]]`

        Array of [lng, lat] positions

      - `Array[Array[Array[Float]]]`

        Array of linear rings / line strings

      - `Array[Array[Array[Array[Float]]]]`

        Array of polygons

    - `type: :Point | :LineString | :Polygon | 3 more`

      Geometry type

      - `:Point`

      - `:LineString`

      - `:Polygon`

      - `:MultiPoint`

      - `:MultiLineString`

      - `:MultiPolygon`

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

    Snap result metadata

    - `distance_m: Float`

      Distance from the input coordinate to the snapped point in meters

    - `edge_id: Integer`

      ID of the road network edge that was snapped to

    - `edge_length_m: Float`

      Length of the matched road edge in meters

    - `highway: String`

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

    - `osm_way_id: Integer`

      OSM way ID of the matched road segment

    - `surface: String`

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

  - `type: :Feature`

    - `:Feature`

### Example

```ruby
require "plaza"

plaza = Plaza::Client.new(
  api_key: "My API Key",
  environment: "local" # defaults to "production"
)

nearest_result = plaza.routing.nearest(lat: 0, lng: 0)

puts(nearest_result)
```

#### 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

`routing.nearest_post(**kwargs) -> NearestResult`

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

Snap a coordinate to the nearest road

### Parameters

- `lat: Float`

  Latitude

- `lng: Float`

  Longitude

- `output_fields: String`

  Comma-separated property fields to include

- `output_include: String`

  Extra computed fields: bbox, distance, center

- `output_precision: Integer`

  Coordinate decimal precision (1-15, default 7)

- `radius: Integer`

  Search radius in meters (default 500, max 5000)

### Returns

- `class NearestResult`

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

  - `geometry: GeoJsonGeometry`

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

    - `coordinates: Array[Float] | Array[Array[Float]] | Array[Array[Array[Float]]] | Array[Array[Array[Array[Float]]]]`

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

      - `Array[Float]`

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

      - `Array[Array[Float]]`

        Array of [lng, lat] positions

      - `Array[Array[Array[Float]]]`

        Array of linear rings / line strings

      - `Array[Array[Array[Array[Float]]]]`

        Array of polygons

    - `type: :Point | :LineString | :Polygon | 3 more`

      Geometry type

      - `:Point`

      - `:LineString`

      - `:Polygon`

      - `:MultiPoint`

      - `:MultiLineString`

      - `:MultiPolygon`

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

    Snap result metadata

    - `distance_m: Float`

      Distance from the input coordinate to the snapped point in meters

    - `edge_id: Integer`

      ID of the road network edge that was snapped to

    - `edge_length_m: Float`

      Length of the matched road edge in meters

    - `highway: String`

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

    - `osm_way_id: Integer`

      OSM way ID of the matched road segment

    - `surface: String`

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

  - `type: :Feature`

    - `:Feature`

### Example

```ruby
require "plaza"

plaza = Plaza::Client.new(
  api_key: "My API Key",
  environment: "local" # defaults to "production"
)

nearest_result = plaza.routing.nearest_post(lat: 0, lng: 0)

puts(nearest_result)
```

#### 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

`routing.isochrone(**kwargs) -> RoutingIsochroneResponse`

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

Calculate an isochrone from a point

### Parameters

- `lat: Float`

  Latitude

- `lng: Float`

  Longitude

- `time: Float`

  Travel time in seconds (1-7200)

- `mode: String`

  Travel mode (auto, foot, bicycle)

- `output_fields: String`

  Comma-separated property fields to include

- `output_geometry: bool`

  Include geometry (default true)

- `output_include: String`

  Extra computed fields: bbox, center

- `output_precision: Integer`

  Coordinate decimal precision (1-15, default 7)

- `output_simplify: Float`

  Simplify geometry tolerance in meters

### Returns

- `class RoutingIsochroneResponse`

  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: Array[GeoJsonFeature]`

    Array of isochrone polygon Features (multi-contour only)

    - `geometry: GeoJsonGeometry`

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

      - `coordinates: Array[Float] | Array[Array[Float]] | Array[Array[Array[Float]]] | Array[Array[Array[Array[Float]]]]`

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

        - `Array[Float]`

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

        - `Array[Array[Float]]`

          Array of [lng, lat] positions

        - `Array[Array[Array[Float]]]`

          Array of linear rings / line strings

        - `Array[Array[Array[Array[Float]]]]`

          Array of polygons

      - `type: :Point | :LineString | :Polygon | 3 more`

        Geometry type

        - `:Point`

        - `:LineString`

        - `:Polygon`

        - `:MultiPoint`

        - `:MultiLineString`

        - `:MultiPolygon`

    - `properties: Hash[Symbol, untyped]`

      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: String`

      Compound identifier in `type/osm_id` format

  - `geometry: GeoJsonGeometry`

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

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

    Isochrone metadata

    - `area_m2: Float`

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

    - `max_cost_s: Float`

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

    - `mode: :auto | :foot | :bicycle`

      Travel mode used for the isochrone calculation

      - `:auto`

      - `:foot`

      - `:bicycle`

    - `time_seconds: Float`

      Travel time budget in seconds

    - `vertices_reached: Integer`

      Number of road network vertices within the isochrone

  - `type: :Feature | :FeatureCollection`

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

    - `:Feature`

    - `:FeatureCollection`

### Example

```ruby
require "plaza"

plaza = Plaza::Client.new(
  api_key: "My API Key",
  environment: "local" # defaults to "production"
)

response = plaza.routing.isochrone(lat: 0, lng: 0, time: 0)

puts(response)
```

#### 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

`routing.isochrone_post(**kwargs) -> RoutingIsochronePostResponse`

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

Calculate an isochrone from a point

### Parameters

- `lat: Float`

  Latitude

- `lng: Float`

  Longitude

- `time: Float`

  Travel time in seconds (1-7200)

- `mode: String`

  Travel mode (auto, foot, bicycle)

- `output_fields: String`

  Comma-separated property fields to include

- `output_geometry: bool`

  Include geometry (default true)

- `output_include: String`

  Extra computed fields: bbox, center

- `output_precision: Integer`

  Coordinate decimal precision (1-15, default 7)

- `output_simplify: Float`

  Simplify geometry tolerance in meters

### Returns

- `class RoutingIsochronePostResponse`

  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: Array[GeoJsonFeature]`

    Array of isochrone polygon Features (multi-contour only)

    - `geometry: GeoJsonGeometry`

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

      - `coordinates: Array[Float] | Array[Array[Float]] | Array[Array[Array[Float]]] | Array[Array[Array[Array[Float]]]]`

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

        - `Array[Float]`

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

        - `Array[Array[Float]]`

          Array of [lng, lat] positions

        - `Array[Array[Array[Float]]]`

          Array of linear rings / line strings

        - `Array[Array[Array[Array[Float]]]]`

          Array of polygons

      - `type: :Point | :LineString | :Polygon | 3 more`

        Geometry type

        - `:Point`

        - `:LineString`

        - `:Polygon`

        - `:MultiPoint`

        - `:MultiLineString`

        - `:MultiPolygon`

    - `properties: Hash[Symbol, untyped]`

      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: String`

      Compound identifier in `type/osm_id` format

  - `geometry: GeoJsonGeometry`

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

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

    Isochrone metadata

    - `area_m2: Float`

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

    - `max_cost_s: Float`

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

    - `mode: :auto | :foot | :bicycle`

      Travel mode used for the isochrone calculation

      - `:auto`

      - `:foot`

      - `:bicycle`

    - `time_seconds: Float`

      Travel time budget in seconds

    - `vertices_reached: Integer`

      Number of road network vertices within the isochrone

  - `type: :Feature | :FeatureCollection`

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

    - `:Feature`

    - `:FeatureCollection`

### Example

```ruby
require "plaza"

plaza = Plaza::Client.new(
  api_key: "My API Key",
  environment: "local" # defaults to "production"
)

response = plaza.routing.isochrone_post(lat: 0, lng: 0, time: 0)

puts(response)
```

#### 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

`routing.matrix(**kwargs) -> MatrixResult`

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

Calculate a distance matrix between points

### Parameters

- `destinations: Array[{ lat, lng}]`

  Array of destination coordinates (max 50)

  - `lat: Float`

    Latitude in decimal degrees (-90 to 90)

  - `lng: Float`

    Longitude in decimal degrees (-180 to 180)

- `origins: Array[{ lat, lng}]`

  Array of origin coordinates (max 50)

  - `lat: Float`

    Latitude in decimal degrees (-90 to 90)

  - `lng: Float`

    Longitude in decimal degrees (-180 to 180)

- `annotations: String`

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

- `fallback_speed: Float`

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

- `mode: :auto | :foot | :bicycle`

  Travel mode (default: `auto`)

  - `:auto`

  - `:foot`

  - `:bicycle`

### Returns

- `Hash[Symbol, untyped]`

  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

```ruby
require "plaza"

plaza = Plaza::Client.new(
  api_key: "My API Key",
  environment: "local" # defaults to "production"
)

matrix_result = plaza.routing.matrix(
  destinations: [{lat: 48.8584, lng: 2.2945}],
  origins: [{lat: 48.8566, lng: 2.3522}, {lat: 48.8606, lng: 2.3376}]
)

puts(matrix_result)
```

#### Response

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

## Domain Types

### Matrix Request

- `class MatrixRequest`

  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[{ lat, lng}]`

    Array of destination coordinates (max 50)

    - `lat: Float`

      Latitude in decimal degrees (-90 to 90)

    - `lng: Float`

      Longitude in decimal degrees (-180 to 180)

  - `origins: Array[{ lat, lng}]`

    Array of origin coordinates (max 50)

    - `lat: Float`

      Latitude in decimal degrees (-90 to 90)

    - `lng: Float`

      Longitude in decimal degrees (-180 to 180)

  - `annotations: String`

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

  - `fallback_speed: Float`

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

  - `mode: :auto | :foot | :bicycle`

    Travel mode (default: `auto`)

    - `:auto`

    - `:foot`

    - `:bicycle`

### Matrix Result

- `Hash[Symbol, untyped]`

  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

- `class NearestResult`

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

  - `geometry: GeoJsonGeometry`

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

    - `coordinates: Array[Float] | Array[Array[Float]] | Array[Array[Array[Float]]] | Array[Array[Array[Array[Float]]]]`

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

      - `Array[Float]`

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

      - `Array[Array[Float]]`

        Array of [lng, lat] positions

      - `Array[Array[Array[Float]]]`

        Array of linear rings / line strings

      - `Array[Array[Array[Array[Float]]]]`

        Array of polygons

    - `type: :Point | :LineString | :Polygon | 3 more`

      Geometry type

      - `:Point`

      - `:LineString`

      - `:Polygon`

      - `:MultiPoint`

      - `:MultiLineString`

      - `:MultiPolygon`

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

    Snap result metadata

    - `distance_m: Float`

      Distance from the input coordinate to the snapped point in meters

    - `edge_id: Integer`

      ID of the road network edge that was snapped to

    - `edge_length_m: Float`

      Length of the matched road edge in meters

    - `highway: String`

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

    - `osm_way_id: Integer`

      OSM way ID of the matched road segment

    - `surface: String`

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

  - `type: :Feature`

    - `:Feature`

### Route Request

- `class RouteRequest`

  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: { lat, lng}`

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

    - `lat: Float`

      Latitude in decimal degrees (-90 to 90)

    - `lng: Float`

      Longitude in decimal degrees (-180 to 180)

  - `origin: { lat, lng}`

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

    - `lat: Float`

      Latitude in decimal degrees (-90 to 90)

    - `lng: Float`

      Longitude in decimal degrees (-180 to 180)

  - `alternatives: Integer`

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

  - `annotations: bool`

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

  - `depart_at: Time`

    Departure time for traffic-aware routing (ISO 8601)

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

    Electric vehicle parameters for EV-aware routing

    - `battery_capacity_wh: Float`

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

    - `connector_types: Array[String]`

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

    - `initial_charge_pct: Float`

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

    - `min_charge_pct: Float`

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

    - `min_power_kw: Float`

      Minimum charger power in kilowatts

  - `exclude: String`

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

  - `geometries: :geojson | :polyline | :polyline6`

    Geometry encoding format. Default: `geojson`.

    - `:geojson`

    - `:polyline`

    - `:polyline6`

  - `mode: :auto | :foot | :bicycle`

    Travel mode (default: `auto`)

    - `:auto`

    - `:foot`

    - `:bicycle`

  - `overview: :full | :simplified | :false`

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

    - `:full`

    - `:simplified`

    - `:false`

  - `steps: bool`

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

  - `traffic_model: :best_guess | :optimistic | :pessimistic`

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

    - `:best_guess`

    - `:optimistic`

    - `:pessimistic`

  - `waypoints: Array[{ lat, lng}]`

    Intermediate waypoints to visit in order (maximum 25)

    - `lat: Float`

      Latitude in decimal degrees (-90 to 90)

    - `lng: Float`

      Longitude in decimal degrees (-180 to 180)

### Route Result

- `class RouteResult`

  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: GeoJsonGeometry`

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

    - `coordinates: Array[Float] | Array[Array[Float]] | Array[Array[Array[Float]]] | Array[Array[Array[Array[Float]]]]`

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

      - `Array[Float]`

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

      - `Array[Array[Float]]`

        Array of [lng, lat] positions

      - `Array[Array[Array[Float]]]`

        Array of linear rings / line strings

      - `Array[Array[Array[Array[Float]]]]`

        Array of polygons

    - `type: :Point | :LineString | :Polygon | 3 more`

      Geometry type

      - `:Point`

      - `:LineString`

      - `:Polygon`

      - `:MultiPoint`

      - `:MultiLineString`

      - `:MultiPolygon`

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

    Route metadata

    - `distance_m: Float`

      Total route distance in meters

    - `duration_s: Float`

      Estimated travel duration in seconds

    - `annotations: Hash[Symbol, untyped]`

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

    - `charge_profile: Array[Array[Float]]`

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

    - `charging_stops: Array[Hash[Symbol, untyped]]`

      Recommended charging stops along the route (EV routes only)

    - `edges: Array[Hash[Symbol, untyped]]`

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

    - `energy_used_wh: Float`

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

  - `type: :Feature`

    - `:Feature`