# Routing

## Calculate a route between two points

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

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

Calculate a route between two points

### Parameters

- `destination: Destination`

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

  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: Optional[int]`

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

- `annotations: Optional[bool]`

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

- `depart_at: Optional[Union[str, datetime, null]]`

  Departure time for traffic-aware routing (ISO 8601)

- `ev: Optional[Ev]`

  Electric vehicle parameters for EV-aware routing

  - `battery_capacity_wh: float`

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

  - `connector_types: Optional[SequenceNotStr[str]]`

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

  - `initial_charge_pct: Optional[float]`

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

  - `min_charge_pct: Optional[float]`

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

  - `min_power_kw: Optional[float]`

    Minimum charger power in kilowatts

- `exclude: Optional[str]`

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

- `geometries: Optional[Literal["geojson", "polyline", "polyline6"]]`

  Geometry encoding format. Default: `geojson`.

  - `"geojson"`

  - `"polyline"`

  - `"polyline6"`

- `mode: Optional[Literal["auto", "foot", "bicycle"]]`

  Travel mode (default: `auto`)

  - `"auto"`

  - `"foot"`

  - `"bicycle"`

- `overview: Optional[Literal["full", "simplified", "false"]]`

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

  - `"full"`

  - `"simplified"`

  - `"false"`

- `steps: Optional[bool]`

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

- `traffic_model: Optional[Literal["best_guess", "optimistic", "pessimistic"]]`

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

  - `"best_guess"`

  - `"optimistic"`

  - `"pessimistic"`

- `waypoints: Optional[Iterable[Waypoint]]`

  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: Union[List[float], List[List[float]], List[List[List[float]]], List[List[List[List[float]]]]]`

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

      - `List[float]`

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

      - `List[List[float]]`

        Array of [lng, lat] positions

      - `List[List[List[float]]]`

        Array of linear rings / line strings

      - `List[List[List[List[float]]]]`

        Array of polygons

    - `type: Literal["Point", "LineString", "Polygon", 3 more]`

      Geometry type

      - `"Point"`

      - `"LineString"`

      - `"Polygon"`

      - `"MultiPoint"`

      - `"MultiLineString"`

      - `"MultiPolygon"`

  - `properties: Properties`

    Route metadata

    - `distance_m: float`

      Total route distance in meters

    - `duration_s: float`

      Estimated travel duration in seconds

    - `annotations: Optional[Dict[str, object]]`

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

    - `charge_profile: Optional[List[List[float]]]`

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

    - `charging_stops: Optional[List[Dict[str, object]]]`

      Recommended charging stops along the route (EV routes only)

    - `edges: Optional[List[Dict[str, object]]]`

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

    - `energy_used_wh: Optional[float]`

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

  - `type: Literal["Feature"]`

    - `"Feature"`

### Example

```python
import os
from plaza import Plaza

client = Plaza(
    api_key=os.environ.get("PLAZA_API_KEY"),  # This is the default and can be omitted
)
route_result = client.routing.route(
    destination={
        "lat": 48.8584,
        "lng": 2.2945,
    },
    origin={
        "lat": 48.8566,
        "lng": 2.3522,
    },
)
print(route_result.geometry)
```

#### 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(RoutingNearestParams**kwargs)  -> NearestResult`

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

Snap a coordinate to the nearest road

### Parameters

- `lat: float`

  Latitude

- `lng: float`

  Longitude

- `output_fields: Optional[str]`

  Comma-separated property fields to include

- `output_include: Optional[str]`

  Extra computed fields: bbox, distance, center

- `output_precision: Optional[int]`

  Coordinate decimal precision (1-15, default 7)

- `radius: Optional[int]`

  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: Union[List[float], List[List[float]], List[List[List[float]]], List[List[List[List[float]]]]]`

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

      - `List[float]`

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

      - `List[List[float]]`

        Array of [lng, lat] positions

      - `List[List[List[float]]]`

        Array of linear rings / line strings

      - `List[List[List[List[float]]]]`

        Array of polygons

    - `type: Literal["Point", "LineString", "Polygon", 3 more]`

      Geometry type

      - `"Point"`

      - `"LineString"`

      - `"Polygon"`

      - `"MultiPoint"`

      - `"MultiLineString"`

      - `"MultiPolygon"`

  - `properties: Properties`

    Snap result metadata

    - `distance_m: Optional[float]`

      Distance from the input coordinate to the snapped point in meters

    - `edge_id: Optional[int]`

      ID of the road network edge that was snapped to

    - `edge_length_m: Optional[float]`

      Length of the matched road edge in meters

    - `highway: Optional[str]`

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

    - `osm_way_id: Optional[int]`

      OSM way ID of the matched road segment

    - `surface: Optional[str]`

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

  - `type: Literal["Feature"]`

    - `"Feature"`

### Example

```python
import os
from plaza import Plaza

client = Plaza(
    api_key=os.environ.get("PLAZA_API_KEY"),  # This is the default and can be omitted
)
nearest_result = client.routing.nearest(
    lat=0,
    lng=0,
)
print(nearest_result.geometry)
```

#### 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(RoutingNearestPostParams**kwargs)  -> NearestResult`

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

Snap a coordinate to the nearest road

### Parameters

- `lat: float`

  Latitude

- `lng: float`

  Longitude

- `output_fields: Optional[str]`

  Comma-separated property fields to include

- `output_include: Optional[str]`

  Extra computed fields: bbox, distance, center

- `output_precision: Optional[int]`

  Coordinate decimal precision (1-15, default 7)

- `radius: Optional[int]`

  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: Union[List[float], List[List[float]], List[List[List[float]]], List[List[List[List[float]]]]]`

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

      - `List[float]`

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

      - `List[List[float]]`

        Array of [lng, lat] positions

      - `List[List[List[float]]]`

        Array of linear rings / line strings

      - `List[List[List[List[float]]]]`

        Array of polygons

    - `type: Literal["Point", "LineString", "Polygon", 3 more]`

      Geometry type

      - `"Point"`

      - `"LineString"`

      - `"Polygon"`

      - `"MultiPoint"`

      - `"MultiLineString"`

      - `"MultiPolygon"`

  - `properties: Properties`

    Snap result metadata

    - `distance_m: Optional[float]`

      Distance from the input coordinate to the snapped point in meters

    - `edge_id: Optional[int]`

      ID of the road network edge that was snapped to

    - `edge_length_m: Optional[float]`

      Length of the matched road edge in meters

    - `highway: Optional[str]`

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

    - `osm_way_id: Optional[int]`

      OSM way ID of the matched road segment

    - `surface: Optional[str]`

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

  - `type: Literal["Feature"]`

    - `"Feature"`

### Example

```python
import os
from plaza import Plaza

client = Plaza(
    api_key=os.environ.get("PLAZA_API_KEY"),  # This is the default and can be omitted
)
nearest_result = client.routing.nearest_post(
    lat=0,
    lng=0,
)
print(nearest_result.geometry)
```

#### 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(RoutingIsochroneParams**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: Optional[str]`

  Travel mode (auto, foot, bicycle)

- `output_fields: Optional[str]`

  Comma-separated property fields to include

- `output_geometry: Optional[bool]`

  Include geometry (default true)

- `output_include: Optional[str]`

  Extra computed fields: bbox, center

- `output_precision: Optional[int]`

  Coordinate decimal precision (1-15, default 7)

- `output_simplify: Optional[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: Optional[List[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: Union[List[float], List[List[float]], List[List[List[float]]], List[List[List[List[float]]]]]`

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

        - `List[float]`

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

        - `List[List[float]]`

          Array of [lng, lat] positions

        - `List[List[List[float]]]`

          Array of linear rings / line strings

        - `List[List[List[List[float]]]]`

          Array of polygons

      - `type: Literal["Point", "LineString", "Polygon", 3 more]`

        Geometry type

        - `"Point"`

        - `"LineString"`

        - `"Polygon"`

        - `"MultiPoint"`

        - `"MultiLineString"`

        - `"MultiPolygon"`

    - `properties: Dict[str, object]`

      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: Literal["Feature"]`

      Always `Feature`

      - `"Feature"`

    - `id: Optional[str]`

      Compound identifier in `type/osm_id` format

  - `geometry: Optional[GeoJsonGeometry]`

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

  - `properties: Optional[Properties]`

    Isochrone metadata

    - `area_m2: Optional[float]`

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

    - `max_cost_s: Optional[float]`

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

    - `mode: Optional[Literal["auto", "foot", "bicycle"]]`

      Travel mode used for the isochrone calculation

      - `"auto"`

      - `"foot"`

      - `"bicycle"`

    - `time_seconds: Optional[float]`

      Travel time budget in seconds

    - `vertices_reached: Optional[int]`

      Number of road network vertices within the isochrone

  - `type: Optional[Literal["Feature", "FeatureCollection"]]`

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

    - `"Feature"`

    - `"FeatureCollection"`

### Example

```python
import os
from plaza import Plaza

client = Plaza(
    api_key=os.environ.get("PLAZA_API_KEY"),  # This is the default and can be omitted
)
response = client.routing.isochrone(
    lat=0,
    lng=0,
    time=0,
)
print(response.features)
```

#### 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(RoutingIsochronePostParams**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: Optional[str]`

  Travel mode (auto, foot, bicycle)

- `output_fields: Optional[str]`

  Comma-separated property fields to include

- `output_geometry: Optional[bool]`

  Include geometry (default true)

- `output_include: Optional[str]`

  Extra computed fields: bbox, center

- `output_precision: Optional[int]`

  Coordinate decimal precision (1-15, default 7)

- `output_simplify: Optional[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: Optional[List[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: Union[List[float], List[List[float]], List[List[List[float]]], List[List[List[List[float]]]]]`

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

        - `List[float]`

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

        - `List[List[float]]`

          Array of [lng, lat] positions

        - `List[List[List[float]]]`

          Array of linear rings / line strings

        - `List[List[List[List[float]]]]`

          Array of polygons

      - `type: Literal["Point", "LineString", "Polygon", 3 more]`

        Geometry type

        - `"Point"`

        - `"LineString"`

        - `"Polygon"`

        - `"MultiPoint"`

        - `"MultiLineString"`

        - `"MultiPolygon"`

    - `properties: Dict[str, object]`

      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: Literal["Feature"]`

      Always `Feature`

      - `"Feature"`

    - `id: Optional[str]`

      Compound identifier in `type/osm_id` format

  - `geometry: Optional[GeoJsonGeometry]`

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

  - `properties: Optional[Properties]`

    Isochrone metadata

    - `area_m2: Optional[float]`

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

    - `max_cost_s: Optional[float]`

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

    - `mode: Optional[Literal["auto", "foot", "bicycle"]]`

      Travel mode used for the isochrone calculation

      - `"auto"`

      - `"foot"`

      - `"bicycle"`

    - `time_seconds: Optional[float]`

      Travel time budget in seconds

    - `vertices_reached: Optional[int]`

      Number of road network vertices within the isochrone

  - `type: Optional[Literal["Feature", "FeatureCollection"]]`

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

    - `"Feature"`

    - `"FeatureCollection"`

### Example

```python
import os
from plaza import Plaza

client = Plaza(
    api_key=os.environ.get("PLAZA_API_KEY"),  # This is the default and can be omitted
)
response = client.routing.isochrone_post(
    lat=0,
    lng=0,
    time=0,
)
print(response.features)
```

#### 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(RoutingMatrixParams**kwargs)  -> MatrixResult`

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

Calculate a distance matrix between points

### Parameters

- `destinations: Iterable[Destination]`

  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: Iterable[Origin]`

  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: Optional[str]`

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

- `fallback_speed: Optional[float]`

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

- `mode: Optional[Literal["auto", "foot", "bicycle"]]`

  Travel mode (default: `auto`)

  - `"auto"`

  - `"foot"`

  - `"bicycle"`

### Returns

- `Dict[str, object]`

### Example

```python
import os
from plaza import Plaza

client = Plaza(
    api_key=os.environ.get("PLAZA_API_KEY"),  # This is the default and can be omitted
)
matrix_result = client.routing.matrix(
    destinations=[{
        "lat": 48.8584,
        "lng": 2.2945,
    }],
    origins=[{
        "lat": 48.8566,
        "lng": 2.3522,
    }, {
        "lat": 48.8606,
        "lng": 2.3376,
    }],
)
print(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: List[Destination]`

    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: List[Origin]`

    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: Optional[str]`

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

  - `fallback_speed: Optional[float]`

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

  - `mode: Optional[Literal["auto", "foot", "bicycle"]]`

    Travel mode (default: `auto`)

    - `"auto"`

    - `"foot"`

    - `"bicycle"`

### Matrix Result

- `Dict[str, object]`

  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: Union[List[float], List[List[float]], List[List[List[float]]], List[List[List[List[float]]]]]`

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

      - `List[float]`

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

      - `List[List[float]]`

        Array of [lng, lat] positions

      - `List[List[List[float]]]`

        Array of linear rings / line strings

      - `List[List[List[List[float]]]]`

        Array of polygons

    - `type: Literal["Point", "LineString", "Polygon", 3 more]`

      Geometry type

      - `"Point"`

      - `"LineString"`

      - `"Polygon"`

      - `"MultiPoint"`

      - `"MultiLineString"`

      - `"MultiPolygon"`

  - `properties: Properties`

    Snap result metadata

    - `distance_m: Optional[float]`

      Distance from the input coordinate to the snapped point in meters

    - `edge_id: Optional[int]`

      ID of the road network edge that was snapped to

    - `edge_length_m: Optional[float]`

      Length of the matched road edge in meters

    - `highway: Optional[str]`

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

    - `osm_way_id: Optional[int]`

      OSM way ID of the matched road segment

    - `surface: Optional[str]`

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

  - `type: Literal["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: Destination`

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

    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: Optional[int]`

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

  - `annotations: Optional[bool]`

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

  - `depart_at: Optional[datetime]`

    Departure time for traffic-aware routing (ISO 8601)

  - `ev: Optional[Ev]`

    Electric vehicle parameters for EV-aware routing

    - `battery_capacity_wh: float`

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

    - `connector_types: Optional[List[str]]`

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

    - `initial_charge_pct: Optional[float]`

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

    - `min_charge_pct: Optional[float]`

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

    - `min_power_kw: Optional[float]`

      Minimum charger power in kilowatts

  - `exclude: Optional[str]`

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

  - `geometries: Optional[Literal["geojson", "polyline", "polyline6"]]`

    Geometry encoding format. Default: `geojson`.

    - `"geojson"`

    - `"polyline"`

    - `"polyline6"`

  - `mode: Optional[Literal["auto", "foot", "bicycle"]]`

    Travel mode (default: `auto`)

    - `"auto"`

    - `"foot"`

    - `"bicycle"`

  - `overview: Optional[Literal["full", "simplified", "false"]]`

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

    - `"full"`

    - `"simplified"`

    - `"false"`

  - `steps: Optional[bool]`

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

  - `traffic_model: Optional[Literal["best_guess", "optimistic", "pessimistic"]]`

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

    - `"best_guess"`

    - `"optimistic"`

    - `"pessimistic"`

  - `waypoints: Optional[List[Waypoint]]`

    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: Union[List[float], List[List[float]], List[List[List[float]]], List[List[List[List[float]]]]]`

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

      - `List[float]`

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

      - `List[List[float]]`

        Array of [lng, lat] positions

      - `List[List[List[float]]]`

        Array of linear rings / line strings

      - `List[List[List[List[float]]]]`

        Array of polygons

    - `type: Literal["Point", "LineString", "Polygon", 3 more]`

      Geometry type

      - `"Point"`

      - `"LineString"`

      - `"Polygon"`

      - `"MultiPoint"`

      - `"MultiLineString"`

      - `"MultiPolygon"`

  - `properties: Properties`

    Route metadata

    - `distance_m: float`

      Total route distance in meters

    - `duration_s: float`

      Estimated travel duration in seconds

    - `annotations: Optional[Dict[str, object]]`

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

    - `charge_profile: Optional[List[List[float]]]`

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

    - `charging_stops: Optional[List[Dict[str, object]]]`

      Recommended charging stops along the route (EV routes only)

    - `edges: Optional[List[Dict[str, object]]]`

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

    - `energy_used_wh: Optional[float]`

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

  - `type: Literal["Feature"]`

    - `"Feature"`