Working with Waze Data API

You need live traffic alerts and turn-by-turn routes you can wire into your app this week. By the end of this guide, you’ll query Waze for real-time hazards and jams in a bounding box and fetch routes with alerts between two coordinates using the Waze Data API on Zyla API Hub, with copy-pasteable curl and Python examples that you can drop into your service.

What you get from the Waze Data API

The Waze Data API exposes two core capabilities for navigation use cases:

• Real-time alerts and jams within a geographic rectangle, covering accidents, road closures, hazards, police, and traffic jams.
• Driving directions (routes) between two coordinates, including alerts along each potential route and support for specifying a desired arrival time.

Teams use this to power in-app incident overlays, congestion-aware ETAs, and automated rerouting workflows. All calls go through Zyla API Hub with one account, one API key, and subscription + quota billing (not pay-per-call). Zyla hosts more than 10,000 public APIs across categories, but here we’ll stay focused on Navigation.

Browse the marketplace at https://zylalabs.com and open the Waze Data API listing to review parameters, quota, and current access options. You can also start the 7-day trial directly here: Start 7-day trial on Waze Data API.

Getting started on Zyla API Hub

To call the endpoints:

1. Open the Waze Data API page on Zyla API Hub and click Subscribe or Start Free Trial (when available). The first API typically offers a 7-day trial or 50 requests. There is no Free Plan.
2. Copy your API key from the dashboard.
3. Call the endpoints shown below using Authorization: Bearer YOUR_API_KEY. All requests go to zylalabs.com with the exact paths provided in this article.

Authentication is header-only; do not append API keys to query parameters. Calls are counted against your subscription quota.

Endpoint: Alerts and Jams

Use this to fetch real-time alerts and traffic jams within a rectangular area defined by bottom-left and top-right latitude/longitude pairs. This is ideal for map tiles, city overlays, and geofenced monitoring.

• Method: GET
• URL: https://zylalabs.com/api/4814/waze-data-api/6003/alerts-and-jams
• Required parameters:
  • bottom_left (string): “lat,lon”
  • top_right (string): “lat,lon”
• Optional parameters:
  • max_alerts (string)
  • max_jams (string)

Official curl example (copy/paste):

curl -s -X GET "https://zylalabs.com/api/4814/waze-data-api/6003/alerts-and-jams?bottom_left=51.2800%2C-0.5100&top_right=51.5000%2C-0.0800&max_alerts=100&max_jams=0" \
  -H "Authorization: Bearer YOUR_API_KEY"

Official example response

{
    "status": "OK",
    "request_id": "86b7f40f-b386-4aee-af95-274974d93184",
    "parameters": {
        "bottom_left": [
            "51.2800",
            "-0.5100"
        ],
        "top_right": [
            "51.5000",
            "-0.0800"
        ],
        "max_alerts": 100,
        "max_jams": 0
    },
    "data": {
        "alerts": [
            {
                "alert_id": "alert-1851823848/7b5e52cb-9549-4955-a117-ce19dd01fe9b",
                "type": "HAZARD",
                "subtype": "HAZARD_ON_ROAD_CONSTRUCTION",
                "reported_by": "Causeway one.network",
                "description": ".",
                "image": null,
                "publish_datetime_utc": "2026-07-22T08:30:00.000Z",
                "country": "GB",
                "city": "Mole Valley",
                "street": null,
                "latitude": 51.281508,
                "longitude": -0.369863,
                "num_thumbs_up": 7,
                "alert_reliability": 0,
                "alert_confidence": 0,
                "near_by": null,
                "provider": "Elgin (Road works)",
                "provider_id": "151505923",
                "comments": [],
                "num_comments": 0
            },
            {
                "alert_id": "alert-1191763163/60f6957d-0668-49d6-b43f-710177584187",
                "type": "HAZARD",
                "subtype": "HAZARD_ON_ROAD_CONSTRUCTION",
                "reported_by": "Causeway one.network",
                "description": ".",
                "image": null,
                "publish_datetime_utc": "2026-05-15T13:00:00.000Z",
                "country": "GB",
                "city": "Mole Valley",
                "street": "Durleston Park Dr",
                "latitude": 51.280691,
                "longitude": -0.365612,
                "num_thumbs_up": 39,
                "alert_reliability": 0,
                "alert_confidence": 0,
                "near_by": null,
                "provider": "Elgin (Road works)",
                "provider_id": "149944301",
                "comments": [],
                "num_comments": 0
            },
            {
                "alert_id": "alert-1618880859/60722796-8030-486e-913c-4e683837b754",
                "type": "ROAD_CLOSED",
                "subtype": null,
                "reported_by": "ClosureMonitor",
                "description": "Closed until Jul 31 for roadworks. Ref #151583431",
                "image": null,
                "publish_…

What to use in production:

• status: string indicating success.
• parameters: echo of your request (useful for logging).
• data.alerts: list of alerts in your rectangle. Key fields include:
  • alert_id: stable identifier for de-duplication.
  • type/subtype: classify by hazard, jam, closure, etc.
  • latitude / longitude: plot on your map layer.
  • publish_datetime_utc: UTC timestamp for freshness logic and cache invalidation.
  • city, street: context for user-facing messages.

Python example: fetch and filter construction and closures

This example calls the same endpoint, filters relevant alert types, and prints a minimal payload you can forward to your frontend or alerts pipeline.

import os
import requests

API_KEY = os.getenv("ZYLALABS_API_KEY", "YOUR_API_KEY")
url = "https://zylalabs.com/api/4814/waze-data-api/6003/alerts-and-jams"
params = {
"bottom_left": "51.2800,-0.5100",
"top_right": "51.5000,-0.0800",
"max_alerts": "100",
"max_jams": "0"
}
headers = {
"Authorization": f"Bearer {API_KEY}"
}

resp = requests.get(url, params=params, headers=headers, timeout=20)
resp.raise_for_status()
payload = resp.json()

alerts = payload.get("data", {}).get("alerts", [])
interesting = []
for a in alerts:
atype = a.get("type")
subtype = a.get("subtype")
if atype in ("HAZARD", "ROAD_CLOSED"):
interesting.append({
"id": a.get("alert_id"),
"type": atype,
"subtype": subtype,
"lat": a.get("latitude"),
"lon": a.get("longitude"),
"published_utc": a.get("publish_datetime_utc"),
"city": a.get("city"),
"street": a.get("street"),
"thumbs_up": a.get("num_thumbs_up")
})

print(f"Total alerts in bbox: {len(alerts)}; relevant: {len(interesting)}")
for a in interesting[:5]:
print(a)

Notes:

• Timestamps are UTC in publish_datetime_utc. Convert in your UI if needed, but store UTC for consistency.
• max_alerts and max_jams let you bound the response size if you’re polling frequently.

Endpoint: Driving Directions

Use this to get routes between two coordinates, with alerts along each possible route. You can set a desired arrival time to plan departures accordingly. The response includes route metadata such as length_meters and duration_seconds, plus any relevant alerts.

• Method: GET
• URL: https://zylalabs.com/api/4814/waze-data-api/6004/driving-directions
• Required parameters:
  • source_coordinates (string): “lat,lon”
  • destination_coordinates (string): “lat,lon”

Official curl example (copy/paste):

Typical fields of interest from this endpoint include:

• length_meters: total route length (meters).
• duration_seconds: total route duration (seconds).
• is_fastest, is_toll, is_hov: booleans for route filtering.
• alerts: list of alerts encountered along the route, including type, subtype, and coordinates.

Usage tips:

• Cache route candidates by rounded source/destination to avoid refetching on minor drifts.
• For ETAs in your UI, prefer duration_seconds. Convert to minutes client-side.
• If you store route choices, also store the set of alert_ids returned to detect when a route has changed materially.

Practical implementation patterns

Bounding-box polling for city overlays

• Divide your metro area into tiles (e.g., 0.1° x 0.1°). Poll each tile’s alerts-and-jams at a reasonable cadence for your UX.
• Use max_alerts and max_jams to cap payloads in dense areas.
• De-duplicate by alert_id across tiles and polls. Expire alerts after a time threshold unless refreshed by the API.

Rerouting logic on top of driving directions

• Fetch routes for a driver’s current position to destination every N minutes or after significant position changes.
• When is_fastest flips between alternatives or a ROAD_CLOSED alert appears along the chosen route, trigger a reroute prompt.
• Keep the last-known duration_seconds to compare against new results and compute user-visible “+X min” deltas.

Units, timestamps, and caching

• Distances are in meters, durations in seconds. Persist raw values; format in your locale at the presentation layer.
• Publish times are suffixed with “_utc”. Treat them as UTC for scheduling, alert freshness, and logs.
• For polling endpoints, use short cache lifetimes (tens of seconds to a few minutes) depending on your UI’s tolerance for staleness.

Calling the API from AI agents via MCP

If your workflow uses MCP-compatible clients (e.g., Claude Code, Cursor, Windsurf), you can call any Zyla API, including Waze Data API, through the MCP endpoint. Point your agent or tool to:

MCP

Pass your key as apikey=YOUR_API_KEY in the MCP endpoint URL. The agent can then invoke the same Waze Data API paths you see in this article. This is useful for prototyping chat-driven ops (e.g., “show closures in this bbox” or “fetch fastest route to destination”). For non-agent services, call the REST endpoints directly as shown above. You can always explore more navigation and mapping options on Zyla API Hub.

Error handling and observability

• Log request_id from responses. It helps correlate your logs with Zyla support when needed.
• Validate parameters before calling: ensure bottom_left.lat < top_right.lat and longitudes define a sensible rectangle.
• Gracefully handle empty alerts arrays; lack of data is often a valid state for a quiet region.
• Back off or reduce max_alerts when you’re close to your subscription quota. Check the API page for current access options and pricing details.

Security and deployment checklist

• Store the API key in your server-side secret manager; never expose it in client-side JS.
• Terminate TLS at your edge and call Zyla over HTTPS only (as shown in all examples).
• Implement timeouts on HTTP clients (e.g., 10–20s) and monitor error rates.
• Use allowlists for outbound domains; permit only zylalabs.com and mcp.zylalabs.com where appropriate.

End-to-end snippet: get a route, then overlay alerts in your map

High-level flow:

1. Call driving-directions for source/destination coordinates.
2. Extract alerts from the chosen route to display incident markers.
3. Call alerts-and-jams for the viewport bbox to enrich with nearby incidents not on the route.

You can compose the two endpoints server-side and return a compact payload to your frontend: route polyline or coordinates (when available), duration_seconds, and a merged set of deduplicated alerts keyed by alert_id.

Quick reference

• Alerts and Jams (GET): https://zylalabs.com/api/4814/waze-data-api/6003/alerts-and-jams
• Driving Directions (GET): https://zylalabs.com/api/4814/waze-data-api/6004/driving-directions
• Auth: Authorization: Bearer YOUR_API_KEY
• Billing: subscription + quota (not pay-per-call). First API: 7-day trial or 50 requests. No Free Plan.

FAQs

How often should I poll Alerts and Jams for a city map?
It depends on your UX and quota. Many apps poll every 30–120 seconds for dense areas and use max_alerts to bound payload size. Cache responses briefly and de-duplicate by alert_id.

What units do length_meters and duration_seconds use in Driving Directions?
Meters for distance and seconds for duration. Convert to miles/kilometers and minutes at presentation time.

Are timestamps in local time or UTC?
The sample shows publish_datetime_utc in UTC. Store and compare in UTC, and format to local time in your UI if needed.

Can I call these endpoints from a browser?
Avoid exposing your API key in client-side code. Proxy calls through your backend, which holds the Authorization: Bearer YOUR_API_KEY header.

Where do I find current pricing and quota?
Check the Waze Data API page on Zyla API Hub for current access options and pricing. Subscription is quota-based, not pay-per-call.

Ready to wire live Waze navigation data into your product? Create a free account, get your API key, and start the 7-day trial here: Start 7-day trial on Waze Data API. You can discover more navigation and mapping APIs on Zyla API Hub when you’re ready to expand your stack.