Sign in

v1

latestOpenAPI 3.1.02026-08-0420183200.9 KB
Routing

Calculate an optimized route between a known start and end point.

The optimized route API is a mix of the matrix and normal route API. For an optimized route, the start and end point are fixed, but the intermediate points will be re-ordered to form an optimal route visiting all nodes once.

post/optimized_route/v1

Request body

idstring

An identifier to disambiguate requests (echoed by the server).

costing'auto' | 'auto_traffic' | 'auto_traffic_premium' | 'bus' | 'bus_traffic' | 'bus_traffic_premium' | 'taxi' | 'taxi_traffic' | 'taxi_traffic_premium' | 'truck' | 'truck_traffic' | 'truck_traffic_premium' | 'bicycle' | 'bikeshare' | 'motor_scooter' | 'motorcycle' | 'pedestrian' | 'low_speed_vehicle' required
elevation_intervalnumber float

If greater than zero, attempts to include elevation along the route at regular intervals. The "native" internal resolution is 30m, so we recommend you use this when possible. This number is interpreted as either meters or feet depending on the unit parameter. Elevation for route sections containing a bridge or tunnel is interpolated linearly. This doesn't always match the true elevation of the bridge/tunnel, but it prevents sharp artifacts from the surrounding terrain. This functionality is unique to the routing endpoints and is not available via the elevation API. NOTE: This has no effect on the OSRM response format.

units'km' | 'mi'
language'bg-BG' | 'ca-ES' | 'cs-CZ' | 'da-DK' | 'de-DE' | 'el-GR' | 'en-GB' | 'en-US-x-pirate' | 'en-US' | 'es-ES' | 'et-EE' | 'fi-FI' | 'fr-FR' | 'hi-IN' | 'hu-HU' | 'it-IT' | 'ja-JP' | 'nb-NO' | 'nl-NL' | 'pl-PL' | 'pt-BR' | 'pt-PT' | 'ro-RO' | 'ru-RU' | 'sk-SK' | 'sl-SI' | 'sv-SE' | 'tr-TR' | 'uk-UA'
directions_type'none' | 'maneuvers' | 'instructions'

The level of directional narrative to include. Locations and times will always be returned, but narrative generation verbosity can be controlled with this parameter.

format'json' | 'osrm'

The output response format. The default JSON format is extremely compact and ideal for web or data-constrained use cases where you want to fetch additional attributes on demand in small chunks. The OSRM format is much richer and is configurable with significantly more info for turn-by-turn navigation use cases.

banner_instructionsboolean

Optionally includes helpful banners with timing information for turn-by-turn navigation. This is only available in the OSRM format.

voice_instructionsboolean

Optionally includes voice instructions with timing information for turn-by-turn navigation. This is only available in the OSRM format.

Example request

{
  "costing": "auto",
  "locations": [
    {
      "lat": 40.042072,
      "lon": -76.306572
    },
    {
      "lat": 39.992115,
      "lon": -76.781559
    },
    {
      "lat": 39.984519,
      "lon": -76.6956
    },
    {
      "lat": 39.996586,
      "lon": -76.769028
    },
    {
      "lat": 39.984322,
      "lon": -76.706672
    }
  ],
  "units": "miles"
}

Response

The optimized route, which looks more or less like a normal route response. The only significant difference is that the locations may be re-ordered and annotated with an original_index.

OR

Example response

{
  "trip": {
    "language": "en-US",
    "legs": [
      {
        "maneuvers": [
          {
            "begin_shape_index": 0,
            "cost": 15.508,
            "end_shape_index": 9,
            "instruction": "Drive west on AK 1/Seward Highway.",
            "length": 0.176,
            "street_names": [
              "AK 1",
              "Seward Highway"
            ],
            "time": 11.487,
            "travel_mode": "drive",
            "travel_type": "car",
            "type": 1,
            "verbal_multi_cue": true,
            "verbal_post_transition_instruction": "Continue for 900 feet.",
            "verbal_pre_transition_instruction": "Drive west on Alaska 1, Seward Highway. Then You will arrive at your destination."
          },
          {
            "begin_shape_index": 9,
            "cost": 0,
            "end_shape_index": 9,
            "instruction": "You have arrived at your destination.",
            "length": 0,
            "time": 0,
            "travel_mode": "drive",
            "travel_type": "car",
            "type": 4,
            "verbal_pre_transition_instruction": "You have arrived at your destination.",
            "verbal_transition_alert_instruction": "You will arrive at your destination."
          }
        ],
        "shape": "wzvmrBxalf|GcCrX}A|Nu@jI}@pMkBtZ{@x^_Afj@Inn@`@veB",
        "summary": {
          "cost": 15.508,
          "has_time_restrictions": false,
          "length": 0.176,
          "max_lat": 60.535008,
          "max_lon": -149.543469,
          "min_lat": 60.534715,
          "min_lon": -149.54858,
          "time": 11.487
        }
      }
    ],
    "locations": [
      {
        "lat": 60.534715,
        "lon": -149.543469,
        "original_index": 0,
        "type": "break"
      },
      {
        "lat": 60.53499,
        "lon": -149.54858,
        "original_index": 1,
        "type": "break"
      }
    ],
    "status": 0,
    "status_message": "Found route between points",
    "summary": {
      "cost": 15.508,
      "has_time_restrictions": false,
      "length": 0.176,
      "max_lat": 60.535008,
      "max_lon": -149.543469,
      "min_lat": 60.534715,
      "min_lon": -149.54858,
      "time": 11.487
    },
    "units": "miles"
  }
}