# Waze Route Planning API Documentation

<p><strong>Waze Route Planning API Documentation</strong> 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.</p>

- **Documentation:** [https://scrappa.co/docs/waze-api/waze_route](https://scrappa.co/docs/waze-api/waze_route)
- **API group:** Waze API
- **Endpoint:** `GET https://scrappa.co/api/waze/route`

## Authentication

Send your Scrappa API key in the `X-API-KEY` request header. Paid endpoints also support accountless x402 payments when called without an API key.

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `from_lat` | number | Yes | Latitude of the start point, -90 to 90. Example: 52.520006. |
| `from_lon` | number | Yes | Longitude of the start point, -180 to 180. Example: 13.404954. |
| `to_lat` | number | Yes | Latitude of the end point, -90 to 90. Example: 52.3906. |
| `to_lon` | number | Yes | Longitude of the end point, -180 to 180. Example: 13.0645. |
| `alternatives` | integer | No | Number of routes, 1 to 4. Default: 3. Waze may return fewer. |
| `avoid_tolls` | boolean | No | true to avoid toll roads. Only routes without toll are returned, unless none exists. Default: false. |
| `avoid_ferries` | boolean | No | true to avoid ferries. Only routes without a ferry leg are returned, unless none exists. Default: false. |
| `vehicle_type` | string | No | car, motorcycle or taxi. Default: car. |
| `include` | string | No | Comma separated extras: geometry (route line as [lat, lon] pairs) and steps (turn list). Default: none. |

## Example response

```json
{
    "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

| Status | Error | Description |
| --- | --- | --- |
| 422 | Validation Error | A required query parameter is missing or invalid. This response is not billable. |
| 422 | Points In Two Regions | The two points are in different Waze regions. This response is not billable. |
| 404 | No Route Found | Waze found no route between the two points. This response is not billable. |
| 503 | Service Unavailable | Waze could not be reached, refused the request or changed its answer. This response is not billable. Retry later. |

## More Scrappa resources

- [API documentation](https://scrappa.co/docs)
- [Full LLM-readable API reference](https://scrappa.co/llms-full.txt)
- [OpenAPI specification](https://scrappa.co/docs/api.json)
- [Pricing](https://scrappa.co/pricing)