您的团队本周需要在生产中使用实时导航数据——交通堵塞、事故和您可以信任的路线选项。在本指南结束时，您将能够进行身份验证，从 Zyla API Hub 调用 Waze 数据 API 的导航端点，并解析您实际需要的字段以发送地图、预计到达时间或路线功能。
您可以使用 Waze 数据 API 构建的内容
Waze 数据 API 提供地理区域内的实时警报和堵塞，以及两个坐标之间的行驶方向，包括沿每条路线的警报。这对于以下内容非常有用：
- 应用内交通覆盖（事故、道路封闭、危险、警察、堵塞）。
- 沿路径显示警报的路线/预计到达时间功能。
- 监控城市或走廊周围实时矩形的调度和物流仪表板。
该 API 位于 Zyla API Hub，这是一个拥有超过 10,000 个公共 API 的市场，采用一种订阅模型和一个密钥。
在 Zyla API Hub 上开始
打开 Waze 数据 API 页面并订阅以获取您的密钥。Zyla 上的第一个 API 包含 7 天的试用或 50 次请求；计费为订阅 + 配额（不是按调用计费）。没有免费计划。请查看 API 页面以获取当前访问选项和定价。
- 前往： 开始 7 天的 Waze 数据 API 试用
- 点击订阅或开始免费试用（可用时）。
- 复制您的 API 密钥。
所有请求都使用头 Authorization: Bearer YOUR_API_KEY。基础主机由 Zyla 提供；使用下面显示的确切 Hub URL。
您将使用的导航端点
1) 警报和堵塞
方法：GET
URL：https://zylalabs.com/api/4814/waze-data-api/6003/alerts-and-jams
描述：获取边界矩形内的实时警报和堵塞（左下角和右上角的纬度、经度）。
参数：
- bottom_left（字符串，必需）：51.2800,-0.5100
- top_right（字符串，必需）：51.5000,-0.0800
- max_alerts（字符串，可选）：100
- max_jams（字符串，可选）：0
2) 行驶方向
方法：GET
URL：https://zylalabs.com/api/4814/waze-data-api/6004/driving-directions
描述：获取两个坐标之间的路线/行驶方向。响应包括路线元数据和沿可能路线遇到的警报。支持设置所需的到达时间。
参数：
- source_coordinates（字符串，必需）：32.0852999,34.78176759999999
- destination_coordinates（字符串，必需）：32.7940463,34.989571
进行您的第一次调用：警报和堵塞
复制并粘贴下面的官方 curl。用您的密钥替换 YOUR_API_KEY。保持 URL 和参数与所示完全相同。
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_…您通常会使用的关键字段：
- data.alerts[].type 和 .subtype：类别和子类别（例如，HAZARD_ON_ROAD_CONSTRUCTION，ROAD_CLOSED）。
- latitude，longitude：在您的地图上放置的点。
- publish_datetime_utc：用于最近性检查和 TTL 决策的 UTC 时间戳。
- city，street，country：UI 的可选标签。
- num_thumbs_up：快速流行度/验证信号。
Python 示例：在矩形中获取和显示危险
此示例调用相同的警报和堵塞端点，过滤 ROAD_CLOSED 和 HAZARD，并打印您可以记录或发送到地图覆盖的紧凑行。
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, headers=headers, params=params, timeout=20)
resp.raise_for_status()
payload = resp.json()
alerts = (payload.get("data") or {}).get("alerts") or []
for a in alerts:
a_type = a.get("type")
if a_type in ("ROAD_CLOSED", "HAZARD"):
print(
f"{a.get('publish_datetime_utc')} | {a_type} | "
f"{a.get('subtype')} | {a.get('city')} | "
f"{a.get('latitude')},{a.get('longitude')} "
)
注意：
- Authorization: Bearer YOUR_API_KEY 是必需的。
- 坐标为十进制度。矩形由左下角和右上角对定义。
- 返回的 publish_datetime_utc 中的时间戳为 UTC。存储并以 UTC 进行比较以避免时区漂移。
带有沿路线警报的行驶方向
使用此端点获取候选路线及其上的警报。您可以选择最快的路线，标记收费，并在您的 UI 中突出显示路径上的堵塞。参数为 source_coordinates 和 destination_coordinates，均为纬度、经度字符串。
方法：GET
URL：https://zylalabs.com/api/4814/waze-data-api/6004/driving-directions
参数：
- source_coordinates（字符串，必需）：32.0852999,34.78176759999999
- destination_coordinates（字符串，必需）：32.7940463,34.989571
您可能从响应中消费的示例字段包括：
- route_name：路线的标签。
- length_meters：路线长度（以米为单位）。
- duration_seconds：路线持续时间（以秒为单位）。
- is_toll，is_hov，is_fastest：用于 UI 选择和启发式的标志。
- alerts[]：每条路线的警报，包括类型、子类型、纬度、经度。
有关实时调用和示例响应，请参见 API 页面上的端点。使用上面提到的相同 Authorization 头。
现实世界导航用例
- 地图覆盖：每 N 秒轮询服务区域周围的警报和堵塞矩形，通过 alert_id 去重，通过 publish_datetime_utc 过期。
- 带上下文的预计到达时间：获取行驶方向，选择最快的路线（is_fastest），并根据与驾驶员的接近程度显示前 3 个警报。
- 地理围栏通知：当驾驶员进入边界框时，触发获取并通知前方是否有 ROAD_CLOSED。
- 操作仪表板：如果您只想要事件标记以减少有效负载大小，请设置 max_jams=0。
节省时间的实施注意事项
- 单位：length_meters 为米；duration_seconds 为秒；时间戳为 UTC。
- 边界框：大矩形返回更多警报；调整 max_alerts 以保持移动设备的有效负载较小。
- 缓存：短期缓存（30-60 秒）通常足以实现流畅的地图，而不会消耗您的配额。
- 错误处理：检查状态和 request_id 以进行诊断；记录两者以便追踪。
- 配额：使用为订阅 + 配额。Zyla 上的第一个 API 包含 7 天的试用或 50 次请求——在您的 Zyla 仪表板中监控消耗。有关当前条款，请参见 API 页面。
通过 MCP 从 AI 代理调用 Waze 数据 API
您可以将此 API 接入与 MCP 兼容的开发工具和代理。将您的客户端指向 MCP 端点，并按照这些客户端文档中的说明传递您的 Zyla 密钥。有关 MCP 基础知识，请参考：
在您代理的 MCP 工具定义中，调用上述相同的 Hub URL，并包括 Authorization: Bearer YOUR_API_KEY 头。保持查询参数名称与端点规范相同。
生产检查清单
- 重试策略：瞬态 5xx 带抖动的回退；避免在大矩形上重试风暴。
- 幂等性：使用 alert_id 去重事件。存储每个矩形的最后一次看到的时间戳。
- 隐私：不要记录 PII；该 API 返回适合操作使用的事件元数据。
- 可观察性：将 request_id 附加到日志和仪表板以实现每次调用的可追溯性。
- 推出：在替换主要估算器之前，验证路线持续时间与您的历史预计到达时间。
探索和订阅的地方
浏览 Zyla API Hub 上的目录，以发现更多导航和映射集成，背后只有一个密钥。当您准备好专门使用 Waze 数据 API 时，请在下面开始您的试用并将端点插入到您的服务中：
常见问题解答
Waze 数据 API 在 Zyla 上使用什么身份验证？
在每个请求中发送 Authorization: Bearer YOUR_API_KEY 到上述 Hub URL。
如何限制地图覆盖的有效负载大小？
在警报和堵塞上使用 max_alerts 和 max_jams。对于仅事件地图，设置 max_jams=0。
坐标格式是什么？
所有坐标为十进制度，作为字符串传递，例如 "lat,lon"。边界矩形使用 bottom_left 和 top_right 对。
行驶方向使用哪些单位？
length_meters 为米，duration_seconds 为秒。
是否有免费计划？
没有免费计划。Zyla 上的第一个 API 包含 7 天的试用或 50 次请求；请查看 API 页面以获取当前访问选项和定价。
