Waze Route Planning API Documentation Plan a route between two points. Each route has its rank, distance in meters, travel time in seconds with live traffic (eta_s), free flow time, delay, toll and ferry flags with meters, the main streets, the road types in meters, restricted areas such as low emission zones, the time zone and the bounding box. Ask for the route line and the turn steps with the include parameter. A call returns 1 to 4 alternatives, up to the number you ask for. Both points must be in the same Waze region (North America, Israel or the rest of the world), or the call answers 422. With avoid_tolls or avoid_ferries only routes that follow the filter are returned. If no such route exists, the call returns the routes it found, each flagged with toll and ferry fields, plus a notes list. The route uses the traffic of the moment of the request: a departure time is not available. This is not a traffic layer: alerts and jams of a map area are not part of this API. Cost: 2 credits per successful route. An unknown route (404) and every error cost nothing. Long routes can take 10 to 15 seconds.
Run this endpoint
Endpoint
Parameters
Start with the required fields, then add optional filters only when your use case needs them.
Runnable path
4 required parameters needed before sending a request.
5 optional filters available.
number
Required
Latitude of the start point, -90 to 90. Example: 52.520006.
10
number
Required
Longitude of the start point, -180 to 180. Example: 13.404954.
10
number
Required
Latitude of the end point, -90 to 90. Example: 52.3906.
10
number
Required
Longitude of the end point, -180 to 180. Example: 13.0645.
10
integer
Optional
Number of routes, 1 to 4. Default: 3. Waze may return fewer.
10
boolean
Optional
true to avoid toll roads. Only routes without toll are returned, unless none exists. Default: false.
true
boolean
Optional
true to avoid ferries. Only routes without a ferry leg are returned, unless none exists. Default: false.
true
string
Optional
car, motorcycle or taxi. Default: car.
example
string
Optional
Comma separated extras: geometry (route line as [lat, lon] pairs) and steps (turn list). Default: none.
example
Response Schema
Example response fields are illustrative; inspect the JSON before integrating.
Example response fields
Scan these fields before integrating.
data
meta
success
{
"data": {
"to": {
"lat": 52.3906,
"lon": 13.0645
},
"from": {
"lat": 52.520006,
"lon": 13.404954
},
"count": 1,
"routes": [
{
"bbox": {
"max_lat": 52.52005,
"max_lon": 13.40464,
"min_lat": 52.37223,
"min_lon": 13.0645
},
"rank": 1,
"toll": false,
"eta_s": 2702,
"ferry": false,
"steps": [
{
"lat": 52.520047,
"lon": 13.404642,
"street": "B2 - B5 - Karl-Liebknecht-Stra\u00dfe",
"distance_m": 1501,
"duration_s": 268,
"instruction": "depart"
},
{
"lat": 52.516839,
"lon": 13.38394,
"street": "B2 - B5 - Unter den Linden",
"distance_m": 220,
"duration_s": 42,
"instruction": "turn_right"
},
{
"lat": 52.516621,
"lon": 13.380721,
"street": "B2 - B5 - Wilhelmstra\u00dfe (Mitte)",
"distance_m": 414,
"duration_s": 100,
"instruction": "turn_left"
}
],
"delay_s": 643,
"time_zone": "Europe/Berlin",
"distance_m": 34923,
"road_types": {
"ramp": 2047,
"freeway": 17515,
"major_highway": 8317,
"minor_highway": 3635,
"primary_street": 3409
},
"free_flow_s": 2059,
"toll_meters": 0,
"ferry_meters": 0,
"main_streets": [
"A115 - E51",
"L40 - Nuthestra\u00dfe",
"B2 - B5 - Stra\u00dfe des 17. Juni"
],
"restricted_areas": [
"Umweltzone"
],
"passes_through_danger_area": false
}
],
"avoid_tolls": false,
"vehicle_type": "car",
"avoid_ferries": false
},
"meta": {
"credits": 2,
"billable": true,
"endpoint_family": "route_planning"
},
"success": true
}Errors
Handle these documented responses before retrying or showing customer-facing failures.
Validation Error
A required query parameter is missing or invalid. This response is not billable.
{
"errors": {
"to_lat": [
"The end point needs to_lat and to_lon, e.g. 52.39 and 13.065."
]
},
"message": "The request validation failed"
}Points In Two Regions
The two points are in different Waze regions. This response is not billable.
{
"meta": {
"billable": false,
"retryable": false,
"endpoint_family": "route_planning"
},
"error": {
"code": "ROUTE_REGION_MISMATCH",
"message": "Both points must be in the same Waze region: North America, Israel, or the rest of the world."
},
"success": false
}No Route Found
Waze found no route between the two points. This response is not billable.
{
"meta": {
"billable": false,
"retryable": false,
"endpoint_family": "route_planning"
},
"error": {
"code": "NOT_FOUND",
"message": "No route was found between these points."
},
"success": false
}Service Unavailable
Waze could not be reached, refused the request or changed its answer. This response is not billable. Retry later.
{
"meta": {
"billable": false,
"retryable": true,
"endpoint_family": "route_planning"
},
"error": {
"code": "UPSTREAM_UNAVAILABLE",
"message": "The Waze API is temporarily unavailable. Please retry."
},
"success": false
}Generate Code with AI
Copy a ready-made prompt with all the endpoint details, parameters, and example responses. Paste it into ChatGPT, Claude, or any AI assistant to instantly generate working code.
Try It Live
Test this endpoint in our interactive playground with real data.