# Routing

## Calculate a route between two points

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

Calculate a route between two points

### Body Parameters

- `destination: GeoJsonGeometry`

  Destination point (GeoJSON Point geometry)

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

    GeoJSON coordinates array (nesting depth varies by geometry type)

    - `array of number`

    - `array of array of number`

    - `array of array of array of number`

    - `array of array of array of array of number`

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

    - `"Point"`

    - `"LineString"`

    - `"Polygon"`

    - `"MultiPoint"`

    - `"MultiLineString"`

    - `"MultiPolygon"`

- `origin: GeoJsonGeometry`

  Origin point (GeoJSON Point geometry)

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

  - `"auto"`

  - `"foot"`

  - `"bicycle"`

### Returns

- `RouteResult = object { geometry, properties, type }`

  - `geometry: GeoJsonGeometry`

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

      GeoJSON coordinates array (nesting depth varies by geometry type)

      - `array of number`

      - `array of array of number`

      - `array of array of array of number`

      - `array of array of array of array of number`

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

      - `"Point"`

      - `"LineString"`

      - `"Polygon"`

      - `"MultiPoint"`

      - `"MultiLineString"`

      - `"MultiPolygon"`

  - `properties: object { distance, duration, mode }`

    - `distance: optional number`

      Total distance in meters

    - `duration: optional number`

      Estimated duration in seconds

    - `mode: optional string`

      Travel mode used

  - `type: "Feature"`

    - `"Feature"`

### Example

```http
curl https://plaza.fyi/api/v1/route \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $PLAZA_API_KEY" \
    -d '{
          "destination": {
            "coordinates": [
              0
            ],
            "type": "Point"
          },
          "origin": {
            "coordinates": [
              0
            ],
            "type": "Point"
          }
        }'
```

## Snap a coordinate to the nearest road

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

Snap a coordinate to the nearest road

### Query Parameters

- `lat: number`

  Latitude

- `lng: number`

  Longitude

- `radius: optional number`

  Search radius in meters (default 500, max 5000)

### Returns

- `NearestResult = object { geometry, properties, type }`

  GeoJSON Point Feature snapped to the nearest road segment

  - `geometry: GeoJsonGeometry`

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

      GeoJSON coordinates array (nesting depth varies by geometry type)

      - `array of number`

      - `array of array of number`

      - `array of array of array of number`

      - `array of array of array of array of number`

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

      - `"Point"`

      - `"LineString"`

      - `"Polygon"`

      - `"MultiPoint"`

      - `"MultiLineString"`

      - `"MultiPolygon"`

  - `properties: object { distance_m, edge_id }`

    - `distance_m: optional number`

      Distance to nearest road in meters

    - `edge_id: optional number`

      Road edge ID

  - `type: "Feature"`

    - `"Feature"`

### Example

```http
curl https://plaza.fyi/api/v1/nearest \
    -H "Authorization: Bearer $PLAZA_API_KEY"
```

#### Response

```json
{
  "geometry": {
    "coordinates": [
      0
    ],
    "type": "Point"
  },
  "properties": {
    "distance_m": 0,
    "edge_id": 0
  },
  "type": "Feature"
}
```

## Calculate an isochrone from a point

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

Calculate an isochrone from a point

### Query Parameters

- `lat: number`

  Latitude

- `lng: number`

  Longitude

- `time: number`

  Travel time in seconds (1-7200)

- `mode: optional string`

  Travel mode (auto, foot, bicycle)

### Returns

- `GeoJsonFeature = object { geometry, properties, type, 2 more }`

  - `geometry: GeoJsonGeometry`

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

      GeoJSON coordinates array (nesting depth varies by geometry type)

      - `array of number`

      - `array of array of number`

      - `array of array of array of number`

      - `array of array of array of array of number`

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

      - `"Point"`

      - `"LineString"`

      - `"Polygon"`

      - `"MultiPoint"`

      - `"MultiLineString"`

      - `"MultiPolygon"`

  - `properties: map[unknown]`

  - `type: "Feature"`

    - `"Feature"`

  - `id: optional string`

    Feature identifier (type/osm_id)

  - `osm_id: optional number`

    OpenStreetMap ID

### Example

```http
curl https://plaza.fyi/api/v1/isochrone \
    -H "Authorization: Bearer $PLAZA_API_KEY"
```

## Calculate a distance matrix between points

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

Calculate a distance matrix between points

### Body Parameters

- `destinations: GeoJsonGeometry`

  Destination points (GeoJSON MultiPoint geometry)

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

    GeoJSON coordinates array (nesting depth varies by geometry type)

    - `array of number`

    - `array of array of number`

    - `array of array of array of number`

    - `array of array of array of array of number`

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

    - `"Point"`

    - `"LineString"`

    - `"Polygon"`

    - `"MultiPoint"`

    - `"MultiLineString"`

    - `"MultiPolygon"`

- `origins: GeoJsonGeometry`

  Origin points (GeoJSON MultiPoint geometry)

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

  Travel mode

  - `"auto"`

  - `"foot"`

  - `"bicycle"`

### Returns

- `MatrixResult = object { distances, durations }`

  - `distances: array of array of number`

    Distance matrix (meters), origins x destinations

  - `durations: array of array of number`

    Duration matrix (seconds), origins x destinations

### Example

```http
curl https://plaza.fyi/api/v1/matrix \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $PLAZA_API_KEY" \
    -d '{
          "destinations": {
            "coordinates": [
              0
            ],
            "type": "Point"
          },
          "origins": {
            "coordinates": [
              0
            ],
            "type": "Point"
          }
        }'
```

#### Response

```json
{
  "distances": [
    [
      0
    ]
  ],
  "durations": [
    [
      0
    ]
  ]
}
```

## Domain Types

### Matrix Request

- `MatrixRequest = object { destinations, origins, mode }`

  - `destinations: GeoJsonGeometry`

    Destination points (GeoJSON MultiPoint geometry)

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

      GeoJSON coordinates array (nesting depth varies by geometry type)

      - `array of number`

      - `array of array of number`

      - `array of array of array of number`

      - `array of array of array of array of number`

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

      - `"Point"`

      - `"LineString"`

      - `"Polygon"`

      - `"MultiPoint"`

      - `"MultiLineString"`

      - `"MultiPolygon"`

  - `origins: GeoJsonGeometry`

    Origin points (GeoJSON MultiPoint geometry)

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

    Travel mode

    - `"auto"`

    - `"foot"`

    - `"bicycle"`

### Matrix Result

- `MatrixResult = object { distances, durations }`

  - `distances: array of array of number`

    Distance matrix (meters), origins x destinations

  - `durations: array of array of number`

    Duration matrix (seconds), origins x destinations

### Nearest Result

- `NearestResult = object { geometry, properties, type }`

  GeoJSON Point Feature snapped to the nearest road segment

  - `geometry: GeoJsonGeometry`

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

      GeoJSON coordinates array (nesting depth varies by geometry type)

      - `array of number`

      - `array of array of number`

      - `array of array of array of number`

      - `array of array of array of array of number`

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

      - `"Point"`

      - `"LineString"`

      - `"Polygon"`

      - `"MultiPoint"`

      - `"MultiLineString"`

      - `"MultiPolygon"`

  - `properties: object { distance_m, edge_id }`

    - `distance_m: optional number`

      Distance to nearest road in meters

    - `edge_id: optional number`

      Road edge ID

  - `type: "Feature"`

    - `"Feature"`

### Route Request

- `RouteRequest = object { destination, origin, mode }`

  - `destination: GeoJsonGeometry`

    Destination point (GeoJSON Point geometry)

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

      GeoJSON coordinates array (nesting depth varies by geometry type)

      - `array of number`

      - `array of array of number`

      - `array of array of array of number`

      - `array of array of array of array of number`

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

      - `"Point"`

      - `"LineString"`

      - `"Polygon"`

      - `"MultiPoint"`

      - `"MultiLineString"`

      - `"MultiPolygon"`

  - `origin: GeoJsonGeometry`

    Origin point (GeoJSON Point geometry)

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

    - `"auto"`

    - `"foot"`

    - `"bicycle"`

### Route Result

- `RouteResult = object { geometry, properties, type }`

  - `geometry: GeoJsonGeometry`

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

      GeoJSON coordinates array (nesting depth varies by geometry type)

      - `array of number`

      - `array of array of number`

      - `array of array of array of number`

      - `array of array of array of array of number`

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

      - `"Point"`

      - `"LineString"`

      - `"Polygon"`

      - `"MultiPoint"`

      - `"MultiLineString"`

      - `"MultiPolygon"`

  - `properties: object { distance, duration, mode }`

    - `distance: optional number`

      Total distance in meters

    - `duration: optional number`

      Estimated duration in seconds

    - `mode: optional string`

      Travel mode used

  - `type: "Feature"`

    - `"Feature"`