您需要实时交通警报和可以集成到您应用程序中的逐步路线。本指南结束时，您将使用 Waze 数据 API 在 Zyla API Hub 中查询实时危险和拥堵，并获取两个坐标之间带有警报的路线，附带可复制的 curl 和 Python 示例，您可以将其放入您的服务中。
您从 Waze 数据 API 获得的内容
Waze 数据 API 为导航用例提供了两个核心功能：
- 在一个地理矩形内的实时警报和拥堵，涵盖事故、道路封闭、危险、警察和交通堵塞。
- 两个坐标之间的驾驶方向（路线），包括每条潜在路线上的警报，并支持指定所需的到达时间。
团队使用此功能为应用内事件覆盖、拥堵感知的 ETA 和自动重路由工作流提供动力。所有调用通过 Zyla API Hub 进行，使用一个帐户、一个 API 密钥和订阅 + 配额计费（不是按调用计费）。Zyla 在各个类别中托管超过 10,000 个公共 API，但在这里我们将专注于导航。
浏览市场，访问 https://zylalabs.com，打开 Waze 数据 API 列表以查看参数、配额和当前访问选项。您还可以直接在这里开始 7 天试用：开始 Waze 数据 API 的 7 天试用。
在 Zyla API Hub 上入门
要调用端点：
- 打开 Zyla API Hub 上的 Waze 数据 API 页面，点击订阅或开始免费试用（如有提供）。第一个 API 通常提供 7 天试用或 50 次请求。没有免费计划。
- 从仪表板复制您的 API 密钥。
- 使用 Authorization: Bearer YOUR_API_KEY 调用下面显示的端点。所有请求都发送到 zylalabs.com，路径与本文中提供的完全相同。
身份验证仅限于头部；请勿将 API 密钥附加到查询参数中。调用计入您的订阅配额。
端点：警报和拥堵
使用此功能获取由左下角和右上角的纬度/经度对定义的矩形区域内的实时警报和交通拥堵。这对于地图切片、城市覆盖和地理围栏监控非常理想。
- 方法：GET
- URL：https://zylalabs.com/api/4814/waze-data-api/6003/alerts-and-jams
- 所需参数：
- bottom_left (string): “lat,lon”
- top_right (string): “lat,lon”
- 可选参数：
- max_alerts (string)
- max_jams (string)
官方 curl 示例（复制/粘贴）：
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"官方示例响应
{
"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": "因道路施工关闭，直至 7 月 31 日。参考 #151583431",
"image": null,
"publish_…在生产中使用的内容：
- status：指示成功的字符串。
- parameters：请求的回显（对日志记录很有用）。
- data.alerts：您矩形区域内的警报列表。关键字段包括：
- alert_id：用于去重的稳定标识符。
- type/subtype：按危险、拥堵、封闭等分类。
- latitude / longitude：在您的地图层上绘制。
- publish_datetime_utc：用于新鲜度逻辑和缓存失效的 UTC 时间戳。
- city, street：用户面向消息的上下文。
Python 示例：获取和过滤施工和封闭
此示例调用相同的端点，过滤相关的警报类型，并打印您可以转发到前端或警报管道的最小有效负载。
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)注意：
- 时间戳以 UTC 格式存储在 publish_datetime_utc 中。如果需要，请在您的 UI 中转换，但存储 UTC 以保持一致性。
- max_alerts 和 max_jams 允许您在频繁轮询时限制响应大小。
端点：驾驶方向
使用此功能获取两个坐标之间的路线，并在每条可能的路线旁边提供警报。您可以设置所需的到达时间，以便相应地计划出发。响应包括路线元数据，例如 length_meters 和 duration_seconds，以及任何相关的警报。
- 方法：GET
- URL：https://zylalabs.com/api/4814/waze-data-api/6004/driving-directions
- 所需参数：
- source_coordinates (string): “lat,lon”
- destination_coordinates (string): “lat,lon”
官方 curl 示例（复制/粘贴）：
此端点的典型关注字段包括：
- length_meters：总路线长度（米）。
- duration_seconds：总路线持续时间（秒）。
- is_fastest, is_toll, is_hov：用于路线过滤的布尔值。
- alerts：沿途遇到的警报列表，包括类型、子类型和坐标。
使用提示：
- 通过四舍五入的源/目的地缓存路线候选，以避免在小偏移时重新获取。
- 对于您 UI 中的 ETA，优先使用 duration_seconds。转换为分钟在客户端进行。
- 如果您存储路线选择，还应存储返回的 alert_ids 集合，以检测路线是否发生了实质性变化。
实际实施模式
城市覆盖的边界框轮询
- 将您的城市区域划分为切片（例如，0.1° x 0.1°）。以合理的频率轮询每个切片的警报和拥堵，以满足您的用户体验。
- 使用 max_alerts 和 max_jams 限制密集区域的有效负载。
- 通过 alert_id 在切片和轮询之间去重。除非通过 API 刷新，否则在时间阈值后过期警报。
在驾驶方向上进行重路由逻辑
- 每 N 分钟或在位置发生重大变化后，为驾驶员的当前位置到目的地获取路线。
- 当 is_fastest 在替代方案之间切换或沿所选路线出现 ROAD_CLOSED 警报时，触发重路由提示。
- 保留最后已知的 duration_seconds，以便与新结果进行比较，并计算用户可见的 “+X min” 差异。
单位、时间戳和缓存
- 距离以米为单位，持续时间以秒为单位。保留原始值；在展示层格式化为您的区域。
- 发布时间后缀为 “_utc”。将其视为 UTC 进行调度、警报新鲜度和日志记录。
- 对于轮询端点，使用短缓存生命周期（从几十秒到几分钟），具体取决于您的 UI 对过时的容忍度。
通过 MCP 从 AI 代理调用 API
如果您的工作流使用 MCP 兼容的客户端（例如，Claude Code、Cursor、Windsurf），您可以通过 MCP 端点调用任何 Zyla API，包括 Waze 数据 API。将您的代理或工具指向：
在 MCP 端点 URL 中将您的密钥作为 apikey=YOUR_API_KEY 传递。然后，代理可以调用您在本文中看到的相同 Waze 数据 API 路径。这对于原型设计聊天驱动的操作（例如，“在此边界框中显示封闭”或“获取到目的地的最快路线”）非常有用。对于非代理服务，请直接调用上述 REST 端点。您可以随时在 Zyla API Hub 上探索更多导航和映射选项。
错误处理和可观察性
- 记录响应中的 request_id。这有助于在需要时将您的日志与 Zyla 支持相关联。
- 在调用之前验证参数：确保 bottom_left.lat < top_right.lat，并且经度定义一个合理的矩形。
- 优雅地处理空警报数组；缺少数据通常是安静区域的有效状态。
- 在接近您的订阅配额时，退避或减少 max_alerts。检查 API 页面以获取当前访问选项和定价详细信息。
安全性和部署检查清单
- 将 API 密钥存储在您的服务器端秘密管理器中；切勿在客户端 JS 中公开。
- 在您的边缘终止 TLS，并仅通过 HTTPS 调用 Zyla（如所有示例所示）。
- 在 HTTP 客户端上实现超时（例如，10-20 秒）并监控错误率。
- 使用出站域的白名单；仅在适当的情况下允许 zylalabs.com 和 mcp.zylalabs.com。
端到端代码片段：获取路线，然后在您的地图中叠加警报
高级流程：
- 调用驾驶方向以获取源/目的地坐标。
- 从所选路线中提取警报以显示事件标记。
- 调用警报和拥堵以获取视口边界框，以丰富不在路线上的附近事件。
您可以在服务器端组合这两个端点，并将紧凑的有效负载返回给您的前端：路线折线或坐标（如可用）、duration_seconds，以及按 alert_id 键入的去重警报的合并集。
快速参考
- 警报和拥堵（GET）：https://zylalabs.com/api/4814/waze-data-api/6003/alerts-and-jams
- 驾驶方向（GET）：https://zylalabs.com/api/4814/waze-data-api/6004/driving-directions
- 身份验证：Authorization: Bearer YOUR_API_KEY
- 计费：订阅 + 配额（不是按调用计费）。第一个 API：7 天试用或 50 次请求。没有免费计划。
常见问题
我应该多久轮询一次城市地图上的警报和拥堵？
这取决于您的用户体验和配额。许多应用程序在密集区域每 30-120 秒轮询一次，并使用 max_alerts 来限制有效负载大小。简要缓存响应并通过 alert_id 去重。
驾驶方向中的 length_meters 和 duration_seconds 使用什么单位？
距离使用米，持续时间使用秒。在展示时转换为英里/公里和分钟。
时间戳是本地时间还是 UTC？
示例显示的 publish_datetime_utc 是 UTC。存储和比较时使用 UTC，并在您的 UI 中根据需要格式化为本地时间。
我可以从浏览器调用这些端点吗？
避免在客户端代码中公开您的 API 密钥。通过您的后端代理调用，该后端持有 Authorization: Bearer YOUR_API_KEY 头。
我在哪里可以找到当前的定价和配额？
请检查 Zyla API Hub 上的 Waze 数据 API 页面以获取当前访问选项和定价。订阅是基于配额的，而不是按调用计费。
准备将实时 Waze 导航数据集成到您的产品中吗？创建一个免费帐户，获取您的 API 密钥，并在这里开始 7 天试用：开始 Waze 数据 API 的 7 天试用。当您准备扩展您的技术栈时，您可以在 Zyla API Hub 上发现更多导航和映射 API。
