Skip to content
Plaza Plaza Docs
GuidesBlogPlaygroundDashboard
API Reference
Routing

Calculate a route between two points

$client->routing->route(Destination destination, Origin origin, ?string format, ?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

ParametersExpand Collapse
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.

format?:optional string

Response format for alternatives: json (default), geojson, csv, ndjson

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)

ReturnsExpand Collapse
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

Calculate a route between two points

<?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],
  format: 'format',
  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);
{
  "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"
}
Returns Examples
{
  "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"
}