# Routing

## Calculate a route between two points

`$client->routing->route(Destination destination, Origin origin, ?int alternatives, ?bool annotations, ?\Datetime departAt, ?Ev ev, ?string exclude, ?Geometries geometries, ?Mode mode, ?Overview overview, ?bool steps, ?TrafficModel trafficModel, ?list<Waypoint> waypoints): 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.

- `origin: Origin`

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

- `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)

- `departAt?:optional \Datetime`

  Departure time for traffic-aware routing (ISO 8601)

- `ev?:optional Ev`

  Electric vehicle parameters for EV-aware routing

- `exclude?:optional string`

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

- `geometries?:optional Geometries`

  Geometry encoding format. Default: `geojson`.

- `mode?:optional Mode`

  Travel mode (default: `auto`)

- `overview?:optional Overview`

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

- `steps?:optional bool`

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

- `trafficModel?:optional TrafficModel`

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

- `waypoints?:optional list<Waypoint>`

  Intermediate waypoints to visit in order (maximum 25)

### Returns

- `RouteResult`

  - `GeoJsonGeometry geometry`

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

  - `Properties properties`

    Route metadata

  - `Type type`

### Example

```php
<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

$client = new Client(apiKey: 'My API Key', environment: 'local');

$routeResult = $client->routing->route(
  destination: ['lat' => 48.8584, 'lng' => 2.2945],
  origin: ['lat' => 48.8566, 'lng' => 2.3522],
  alternatives: 0,
  annotations: true,
  departAt: new \DateTimeImmutable('2019-12-27T18:11:19.117Z'),
  ev: [
    'batteryCapacityWh' => 75000,
    'connectorTypes' => ['string'],
    'initialChargePct' => 0,
    'minChargePct' => 0,
    'minPowerKw' => 0,
  ],
  exclude: 'exclude',
  geometries: 'geojson',
  mode: 'auto',
  overview: 'full',
  steps: true,
  trafficModel: 'best_guess',
  waypoints: [['lat' => 48.8566, 'lng' => 2.3522]],
);

var_dump($routeResult);
```

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

`$client->routing->nearest(float lat, float lng, ?string outputFields, ?string outputInclude, ?int outputPrecision, ?int radius): NearestResult`

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

Snap a coordinate to the nearest road

### Parameters

- `lat: float`

  Latitude

- `lng: float`

  Longitude

- `outputFields?:optional string`

  Comma-separated property fields to include

- `outputInclude?:optional string`

  Extra computed fields: bbox, distance, center

- `outputPrecision?:optional int`

  Coordinate decimal precision (1-15, default 7)

- `radius?:optional int`

  Search radius in meters (default 500, max 5000)

### Returns

- `NearestResult`

  - `GeoJsonGeometry geometry`

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

  - `Properties properties`

    Snap result metadata

  - `Type type`

### Example

```php
<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

$client = new Client(apiKey: 'My API Key', environment: 'local');

$nearestResult = $client->routing->nearest(
  lat: 0,
  lng: 0,
  outputFields: 'output[fields]',
  outputInclude: 'output[include]',
  outputPrecision: 0,
  radius: 0,
);

var_dump($nearestResult);
```

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

`$client->routing->nearestPost(float lat, float lng, ?string outputFields, ?string outputInclude, ?int outputPrecision, ?int radius): NearestResult`

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

Snap a coordinate to the nearest road

### Parameters

- `lat: float`

  Latitude

- `lng: float`

  Longitude

- `outputFields?:optional string`

  Comma-separated property fields to include

- `outputInclude?:optional string`

  Extra computed fields: bbox, distance, center

- `outputPrecision?:optional int`

  Coordinate decimal precision (1-15, default 7)

- `radius?:optional int`

  Search radius in meters (default 500, max 5000)

### Returns

- `NearestResult`

  - `GeoJsonGeometry geometry`

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

  - `Properties properties`

    Snap result metadata

  - `Type type`

### Example

```php
<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

$client = new Client(apiKey: 'My API Key', environment: 'local');

$nearestResult = $client->routing->nearestPost(
  lat: 0,
  lng: 0,
  outputFields: 'output[fields]',
  outputInclude: 'output[include]',
  outputPrecision: 0,
  radius: 0,
);

var_dump($nearestResult);
```

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

`$client->routing->isochrone(float lat, float lng, float time, ?string mode, ?string outputFields, ?bool outputGeometry, ?string outputInclude, ?int outputPrecision, ?float outputSimplify): 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 string`

  Travel mode (auto, foot, bicycle)

- `outputFields?:optional string`

  Comma-separated property fields to include

- `outputGeometry?:optional bool`

  Include geometry (default true)

- `outputInclude?:optional string`

  Extra computed fields: bbox, center

- `outputPrecision?:optional int`

  Coordinate decimal precision (1-15, default 7)

- `outputSimplify?:optional float`

  Simplify geometry tolerance in meters

### Returns

- `RoutingIsochroneResponse`

  - `?list<GeoJsonFeature> features`

    Array of isochrone polygon Features (multi-contour only)

  - `?GeoJsonGeometry geometry`

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

  - `?Properties properties`

    Isochrone metadata

  - `?Type type`

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

### Example

```php
<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

$client = new Client(apiKey: 'My API Key', environment: 'local');

$response = $client->routing->isochrone(
  lat: 0,
  lng: 0,
  time: 0,
  mode: 'mode',
  outputFields: 'output[fields]',
  outputGeometry: true,
  outputInclude: 'output[include]',
  outputPrecision: 0,
  outputSimplify: 0,
);

var_dump($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

`$client->routing->isochronePost(float lat, float lng, float time, ?string mode, ?string outputFields, ?bool outputGeometry, ?string outputInclude, ?int outputPrecision, ?float outputSimplify): 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 string`

  Travel mode (auto, foot, bicycle)

- `outputFields?:optional string`

  Comma-separated property fields to include

- `outputGeometry?:optional bool`

  Include geometry (default true)

- `outputInclude?:optional string`

  Extra computed fields: bbox, center

- `outputPrecision?:optional int`

  Coordinate decimal precision (1-15, default 7)

- `outputSimplify?:optional float`

  Simplify geometry tolerance in meters

### Returns

- `RoutingIsochronePostResponse`

  - `?list<GeoJsonFeature> features`

    Array of isochrone polygon Features (multi-contour only)

  - `?GeoJsonGeometry geometry`

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

  - `?Properties properties`

    Isochrone metadata

  - `?Type type`

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

### Example

```php
<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

$client = new Client(apiKey: 'My API Key', environment: 'local');

$response = $client->routing->isochronePost(
  lat: 0,
  lng: 0,
  time: 0,
  mode: 'mode',
  outputFields: 'output[fields]',
  outputGeometry: true,
  outputInclude: 'output[include]',
  outputPrecision: 0,
  outputSimplify: 0,
);

var_dump($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

`$client->routing->matrix(list<Destination> destinations, list<Origin> origins, ?string annotations, ?float fallbackSpeed, ?Mode mode): MatrixResult`

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

Calculate a distance matrix between points

### Parameters

- `destinations: list<Destination>`

  Array of destination coordinates (max 50)

- `origins: list<Origin>`

  Array of origin coordinates (max 50)

- `annotations?:optional string`

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

- `fallbackSpeed?: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 Mode`

  Travel mode (default: `auto`)

### Returns

- `array<string,mixed>`

  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

```php
<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

$client = new Client(apiKey: 'My API Key', environment: 'local');

$matrixResult = $client->routing->matrix(
  destinations: [['lat' => 48.8584, 'lng' => 2.2945]],
  origins: [
    ['lat' => 48.8566, 'lng' => 2.3522], ['lat' => 48.8606, 'lng' => 2.3376]
  ],
  annotations: 'annotations',
  fallbackSpeed: 1,
  mode: 'auto',
);

var_dump($matrixResult);
```

#### Response

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

## Domain Types

### Matrix Request

- `MatrixRequest`

  - `list<Destination> destinations`

    Array of destination coordinates (max 50)

  - `list<Origin> origins`

    Array of origin coordinates (max 50)

  - `?string annotations`

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

  - `?float fallbackSpeed`

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

  - `?Mode mode`

    Travel mode (default: `auto`)

### Matrix Result

- `array<string,mixed>`

### Nearest Result

- `NearestResult`

  - `GeoJsonGeometry geometry`

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

  - `Properties properties`

    Snap result metadata

  - `Type type`

### Route Request

- `RouteRequest`

  - `Destination destination`

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

  - `Origin origin`

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

  - `?int alternatives`

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

  - `?bool annotations`

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

  - `?\Datetime departAt`

    Departure time for traffic-aware routing (ISO 8601)

  - `?Ev ev`

    Electric vehicle parameters for EV-aware routing

  - `?string exclude`

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

  - `?Geometries geometries`

    Geometry encoding format. Default: `geojson`.

  - `?Mode mode`

    Travel mode (default: `auto`)

  - `?Overview overview`

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

  - `?bool steps`

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

  - `?TrafficModel trafficModel`

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

  - `?list<Waypoint> waypoints`

    Intermediate waypoints to visit in order (maximum 25)

### Route Result

- `RouteResult`

  - `GeoJsonGeometry geometry`

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

  - `Properties properties`

    Route metadata

  - `Type type`