Calculate a route between waypoints

Signed in? Open this endpoint in the dashboard playground, which uses your organization automatically. Signed out, use Try in Playground below with your API key.

GET

/routing

GET

/routing

Calculates a route through two or more ordered waypoints (Valhalla).

Provide each waypoint as latitude,longitude; separate waypoints with |.
waypoints and mode are required. mode=drive is a passenger car.
The default geojson response (application/geo+json) contains route geometry, distance, travel time, legs, steps and turn-by-turn instructions.
format=json returns a plain JSON result; format=xml returns the same structure as XML.
Distances are meters (units=metric) or miles (units=imperial); times are seconds.
details=route_details, elevation and admin_areas make the gateway issue a second Engine call per leg (Valhalla trace_attributes for road attributes and admin areas, height for elevation), so they are slower than a plain route. instruction_details, polyline5 and polyline6 cost nothing extra.

Example: /routing?waypoints=39.7684,-86.1581|41.8781,-87.6298&mode=drive&apiKey=YOUR_API_KEY

Deviation (ignored): traffic is accepted and ignored. Durations are always free-flow and the response reports traffic: free_flow.

Deviation (approximated): type=less_maneuvers is approximated with a Valhalla maneuver penalty; avoid importance is approximated by scaling Valhalla's use_tolls / use_highways / use_ferry preference (1 - importance).

Deviation (unsupported): transit modes are not served (no transit data).

Not supported: mode=transit and mode=approximated_transit are removed from the mode enum and return 400. The upstream 429 quota response is not produced by this service.

Authorization

queryapiKey<token>

Your API key from the dashboard, sent as ?apiKey=<key>.

Query Parameters

waypoints*array<>

Ordered route points. Use latitude,longitude for each point (latitude -90 to 90; longitude -180 to 180) and separate points with |. At least two and at most 1000 waypoints.

Items2 <= items <= 1000

mode*string

Travel profile used for speeds, access rules and restrictions. drive is a passenger car. Truck modes use fixed vehicle dimensions.

Deviation (unsupported): transit and approximated_transit are not available and are removed from the enum.

Value in"walk""hike""scooter""motorcycle""drive""light_truck""bicycle""mountain_bike""road_bike""bus""medium_truck""truck""truck_dangerous_goods""heavy_truck""long_truck"

intermediate_waypoint_mode?string

Treatment of intermediate waypoints. stopover splits the route into independent legs; through_stop splits it into legs while preserving travel direction; pass_through treats it as a via point without creating a new leg.

Default"stopover"

Value in"stopover""through_stop""pass_through"

optimize_stops?boolean

Optimize the order of intermediate waypoints (Valhalla optimized route). The first and last waypoints stay fixed. Only has an effect with three or more waypoints.

Defaultfalse

type?string

Route preference. balanced balances time and distance; short prioritizes distance; less_maneuvers penalizes turns and is supported only for motorized road modes (others return 400).

Deviation (approximated): less_maneuvers applies a fixed Valhalla maneuver penalty; it is not Geoapify's exact algorithm.

Default"balanced"

Value in"balanced""short""less_maneuvers"

units?string

Unit system for distances in the response. metric returns meters; imperial returns miles.

Default"metric"

Value in"metric""imperial"

lang?string

Language code for turn-by-turn instructions. Defaults to en (en-US).

Value in"bg""ca""cs""da""de""el""en-GB""en""es""et""fi""fr""hi""hu""it""ja""nb-NO""nl""pl""pt-BR""pt""ro""ru""sk""sl""sv""tr""uk"

avoid?array<>

Features, locations, polygons or countries to avoid. Separate rules with | (or repeat the parameter). Formats: tolls, ferries, highways (optional :importance 0 to 1, for example tolls:0.8); location:lat,lon; polygon:lat,lon;lat,lon;... (at least 3 points); country_codes:us,ca. location_lonlat / polygon_lonlat take longitude first.

Deviation (ignored): green_zones, transfers and country_codes are accepted but have no effect. tolls and highways are ignored for non-motorized modes.

Deviation (approximated): importance scales Valhalla's preference (1 - importance) rather than Geoapify's weighting; no importance means full avoidance.

details?array<>

Comma-separated additional result data. instruction_details adds maneuver metadata; route_details adds road attributes per step; elevation adds the elevation profile (omitted where no elevation tiles exist); admin_areas adds country/state data and crossings. polyline5 / polyline6 add encoded geometry to the route and every leg without replacing the GeoJSON geometry.

route_details, elevation and admin_areas trigger a second Valhalla call per leg (trace_attributes / height), adding latency on long routes.

traffic?string

Traffic model for motorized modes.

Deviation (ignored): accepted and ignored. Durations are free-flow and the response always reports traffic: free_flow.

Default"free_flow"

Value in"free_flow""approximated"

max_speed?number

Maximum speed for driving, truck, motorcycle, scooter and bus modes. 10 to 252 km/h with units=metric, 6.5 to 155 mph with units=imperial. Has no effect on walking and cycling modes.

Range6.5 <= value <= 252

format?string

geojson returns a GeoJSON FeatureCollection (application/geo+json); json returns route objects with {lon, lat} geometry points; xml returns the JSON structure as XML.

Default"geojson"

Value in"geojson""json""xml"

Response Body

Calculated route with geometry, distance, travel time, legs, steps and instructions. Content type follows format.

response

type*unknown

features*array<>

bbox?array<number>

[minLon, minLat, maxLon, maxLat]

Items4 <= items <= 4

properties*

Echo of the request options.

Example Request

curl -X GET 'https://api.data.graphitelab.ai/v1/routing?waypoints=39.7684%2C-86.1581%7C41.8781%2C-87.6298&mode=drive&intermediate_waypoint_mode=stopover&optimize_stops=true&type=short&units=metric&lang=en&avoid=tolls%3A1%7Cferries&details=instruction_details&traffic=free_flow&max_speed=80&format=geojson'

Example Request

curl -X GET 'https://api.data.graphitelab.ai/v1/routing?waypoints=39.7684%2C-86.1581%7C41.8781%2C-87.6298&mode=drive&intermediate_waypoint_mode=stopover&optimize_stops=true&type=short&units=metric&lang=en&avoid=tolls%3A1%7Cferries&details=instruction_details&traffic=free_flow&max_speed=80&format=geojson'

Example ResponseSchema

{
  "results": [
    {
      "mode": "walk",
      "units": "imperial",
      "waypoints": [
        {
          "original_index": 0,
          "location": [
            -79.3832,
            43.6532
          ]
        },
        {
          "original_index": 1,
          "location": [
            -79.3871,
            43.6426
          ]
        }
      ],
      "distance": 1.047,
      "time": 1196.188,
      "distance_units": "miles",
      "traffic": "free_flow",
      "legs": [
        {
          "time": 1196.188,
          "distance": 1.047,
          "steps": [
            {
              "from_index": 0,
              "to_index": 2,
              "time": 6.804,
              "distance": 0.006,
              "instruction": {
                "text": "Take the stairs."
              }
            },
            {
              "from_index": 2,
              "to_index": 3,
              "time": 5.647,
              "distance": 0.005,
              "instruction": {
                "text": "Turn left onto the walkway."
              }
            },
            {
              "from_index": 3,
              "to_index": 5,
              "time": 19.058,
              "distance": 0.017,
              "instruction": {
                "text": "Turn right onto the walkway."
              }
            }
          ]
        }
      ],
      "toll": false,
      "ferry": false,
      "geometry": [
        [
          {
            "lon": -79.38312,
            "lat": 43.653218
          },
          {
            "lon": -79.383097,
            "lat": 43.653166
          },
          {
            "lon": -79.383085,
            "lat": 43.653139
          }
        ]
      ]
    }
  ],
  "properties": {
    "mode": "walk",
    "units": "imperial",
    "waypoints": [
      {
        "lat": 43.6532,
        "lon": -79.3832
      },
      {
        "lat": 43.6426,
        "lon": -79.3871
      }
    ],
    "traffic": "free_flow"
  },
  "bbox": [
    -79.387196,
    43.642865,
    -79.38276,
    43.653218
  ]
}

{  "results": [    {      "mode": "walk",      "units": "imperial",      "waypoints": [        {          "original_index": 0,          "location": [            -79.3832,            43.6532          ]        },        {          "original_index": 1,          "location": [            -79.3871,            43.6426          ]        }      ],      "distance": 1.047,      "time": 1196.188,      "distance_units": "miles",      "traffic": "free_flow",      "legs": [        {          "time": 1196.188,          "distance": 1.047,          "steps": [            {              "from_index": 0,              "to_index": 2,              "time": 6.804,              "distance": 0.006,              "instruction": {                "text": "Take the stairs."              }            },            {              "from_index": 2,              "to_index": 3,              "time": 5.647,              "distance": 0.005,              "instruction": {                "text": "Turn left onto the walkway."              }            },            {              "from_index": 3,              "to_index": 5,              "time": 19.058,              "distance": 0.017,              "instruction": {                "text": "Turn right onto the walkway."              }            }          ]        }      ],      "toll": false,      "ferry": false,      "geometry": [        [          {            "lon": -79.38312,            "lat": 43.653218          },          {            "lon": -79.383097,            "lat": 43.653166          },          {            "lon": -79.383085,            "lat": 43.653139          }        ]      ]    }  ],  "properties": {    "mode": "walk",    "units": "imperial",    "waypoints": [      {        "lat": 43.6532,        "lon": -79.3832      },      {        "lat": 43.6426,        "lon": -79.3871      }    ],    "traffic": "free_flow"  },  "bbox": [    -79.387196,    43.642865,    -79.38276,    43.653218  ]}

Calculate a route between waypoints

AuthorizationCopy Anchor Link

Query ParametersCopy Anchor Link

Response BodyCopy Anchor Link

Authorization

Query Parameters

Response Body