您的团队需要 Waze 级别的事件警报和特定区域的实时交通拥堵，您需要一个可以在本周交付的端点。通过本文，您将查询一个返回 Waze 警报和拥堵的真实 API，解析响应，并了解如何从后端和通过 MCP 从 AI 代理使用它。
您可以使用此 API 构建的内容
Waze 数据 API 提供了开发人员常常要求的两项功能：
- 在一个地理矩形内的实时警报和拥堵（事故、道路封闭、危险、警察、交通拥堵等），以便您可以在地图上标记事件、触发重新规划或警告现场团队。
- 带有沿候选路线的警报的驾驶方向，支持路线选择和 ETA 敏感工作流。
您将通过单个 Zyla API Hub 订阅和 API 密钥调用这些端点。无需直接集成 Waze。
在 Zyla API Hub 上入门
打开 Zyla API Hub 上的 Waze 数据 API 列表并订阅。该中心使用订阅 + 配额模型（不是按调用付费）。首次访问此 API 时，您可以开始 7 天的试用或最多 50 次请求——请查看项目页面以获取当前访问选项和定价。在订阅后，复制您的 API 密钥并在授权头中使用，如下所示。
警报和拥堵端点
此端点返回在由左下角和右上角经纬度对定义的矩形区域内的实时警报和拥堵。
- 方法：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
- 认证：Authorization: Bearer YOUR_API_KEY
您可以复制的 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_…您在大多数应用中实际使用的内容：
- 用于请求跟踪的状态和 request_id。
- 参数以确认您的边界框和限制已应用。
- data.alerts[] 以迭代并提取字段，如类型、子类型、纬度、经度、publish_datetime_utc（UTC 时间戳）、城市、街道和提供者。
节省时间的注意事项：
- 坐标是十进制度，字符串中的顺序为纬度、经度（例如，“51.2800,-0.5100”）。
- publish_datetime_utc 是 UTC。如果您的 UI 显示本地时间，请在边缘转换。
- 当 max_jams=0 时，您将不会收到拥堵；如果需要，请设置一个正值以包含它们。
- 如果您在轮询，请按边界框缓存并添加短 TTL 以控制配额使用。
Python 示例：获取警报并将其映射
此示例调用警报和拥堵端点，解析响应，并为每个警报打印一行紧凑的内容。将 YOUR_API_KEY 替换为您从 Zyla API Hub 获取的密钥。
import os
import requests
API_KEY = os.getenv("Zyla_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=30)
resp.raise_for_status()
payload = resp.json()
if payload.get("status") != "OK":
raise RuntimeError(f"API returned non-OK status: {payload}")
alerts = (payload.get("data") or {}).get("alerts", [])
print(f"received {len(alerts)} alerts")
for a in alerts:
alert_id = a.get("alert_id")
typ = a.get("type")
sub = a.get("subtype")
lat = a.get("latitude")
lng = a.get("longitude")
city = a.get("city")
published_utc = a.get("publish_datetime_utc")
print(f"{published_utc} {typ}/{sub or 'NO_SUBTYPE'} {lat},{lng} {city or '-'} id={alert_id}")驾驶方向端点
当您需要 Waze 路线和每条路线的警报时使用此功能。
- 方法：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
- 认证：Authorization: Bearer YOUR_API_KEY
它在高层次上返回：一个候选路线的数组，带有元数据，如 route_name、length_meters、duration_seconds，以及每条路线的警报列表，包含类型、子类型、纬度和经度。该端点支持根据描述设置所需到达时间；请查阅 API 页面以获取当前在 Hub 中公开的参数选项。
实际模式
- 操作仪表板的事件叠加：在您的服务区域周围的固定网格上轮询警报和拥堵端点。通过 alert_id 去重警报，并通过 publish_datetime_utc 使其过期。
- 地理围栏警报：当车辆或快递员进入接近封闭的边界框时，调用端点一次，并使用类型/子类型和街道（如果可用）推送简洁的通知。
- 发货前的路线验证：调用驾驶方向以获取候选路线，并检查嵌入的警报列表，以选择最快的避免危险或封闭的路线。
- 变更检测：通过 alert_id 和 num_thumbs_up 比较连续响应，以检测新确认的事件，而无需重新计算您的完整地图层。
处理坐标和边界框
- bottom_left 和 top_right 是字符串 "lat,lon"。保持顺序为纬度在前，经度在后。
- 确保您的框没有翻转；纬度向北增加，经度向东增加。
- 对于大城市，将区域划分为瓦片，以保持结果大小可预测并实现轮询的并行化。
- 保留您使用的参数（API 在参数下回显它们）以审核您的摄取管道。
通过 MCP 从 AI 代理调用 API
如果您正在与兼容 MCP 的客户端（例如 Claude Code、Cursor、Windsurf）进行编排，您可以通过市场的 MCP 网关调用相同的 HTTPS 端点。提供您的 Zyla API 密钥，并让代理调用上述文档中的端点 URL。网关可在：
实用提示：
- 在工具定义或每次调用的头中保留 Authorization: Bearer YOUR_API_KEY 头。
- 准确传递查询参数（坐标对的字符串）。
- 在构建自主循环时，强制执行回退或 TTL 以尊重您的配额。
操作指导
- Auth 头格式严格：Authorization: Bearer YOUR_API_KEY。
- 时间戳为 UTC。根据需要在客户端转换。
- 最大限制：使用 max_alerts 和 max_jams 来限制移动客户端或小内存无服务器函数的有效负载大小。
- 错误处理：始终检查顶级状态并保留 request_id 以供日志记录。在非 OK 结果上，记录完整有效负载以供支持。
- 缓存：对于地图瓦片，短 TTL（例如 30-90 秒）在新鲜度和配额效率之间取得平衡。
端到端示例流程
- 选择一个覆盖您目标走廊的边界框（例如，交付路线的 5 公里缓冲区）。
- 使用您的框和警报与拥堵的限制调用警报和拥堵。
- 根据警报类型/子类型渲染标记。以本地转换和相对“年龄”在 UI 中显示 publish_datetime_utc。
- 如果出现关键类型（ROAD_CLOSED），可选择调用驾驶方向以重新评估路径。
- 在带有 ETag 类缓存的定时循环中重复，按 alert_id 键入。
故障排除检查表
- 401 未授权：验证 Authorization 头是否已设置，并且密钥来自 Zyla Hub 中订阅的 Waze 数据 API。
- 空警报数组：确认您的边界框确实与道路网络相交；尝试扩大区域或移除紧密限制。
- 时间显示错误：请记住，publish_datetime_utc 是 UTC；在客户端转换。
- 大有效负载：降低 max_alerts 并通过拆分边界框启用分页式瓦片。
常见问题
此 API 使用什么身份验证？
在每个请求中使用 HTTP 头 Authorization: Bearer YOUR_API_KEY。
我如何设置地理区域？
提供两个字符串：bottom_left 和 top_right，每个字符串为 "lat,lon"（纬度在前，经度在后）。API 返回矩形内的警报和拥堵。
我可以限制结果的数量吗？
可以。使用 max_alerts 和 max_jams 来限制返回的项目数量。
驾驶方向端点是否包括事件？
是的。它在响应中包括每条可能路线的警报，以及长度米和持续时间秒等路线元数据。
是否有免费计划？
没有免费计划。此 API 使用订阅 + 配额模型。您可以在项目页面开始 7 天的试用或最多 50 次请求；请查看列表以获取当前访问选项。
准备好在不从头构建数据管道的情况下插入 Waze 级别的警报和拥堵吗？在市场列表中订阅并获取您的密钥：开始 7 天的 Waze 数据 API 试用。在 Zyla API Hub 上使用一个密钥构建数千个 API，并在本周交付您的集成。
