API para alertas y atascos

Tu equipo necesita alertas de incidentes al nivel de Waze y atascos de tráfico en un área específica, y necesitas un endpoint que puedas implementar esta semana. Al final de este artículo, consultarás una API real que devuelve alertas y atascos de Waze para un cuadro delimitador, analizarás la respuesta y entenderás cómo usarla tanto desde tu backend como desde agentes de IA a través de MCP.

Lo que puedes construir con esta API

La API de Datos de Waze expone dos capacidades que los desarrolladores suelen solicitar:

• Alertas y atascos en tiempo real en un rectángulo geográfico (accidentes, cierres de carreteras, peligros, policía, atascos de tráfico y más) para que puedas marcar incidentes en un mapa, activar redireccionamientos o alertar a equipos de campo.
• Direcciones de conducción con alertas a lo largo de las rutas candidatas, habilitando la elección de ruta y flujos de trabajo sensibles al ETA.

Llamarás a estos endpoints a través de una única suscripción y clave de API de Zyla API Hub. No se requiere integración directa con Waze.

Comenzando en Zyla API Hub

Abre la lista de la API de Datos de Waze en Zyla API Hub y suscríbete. El hub utiliza un modelo de suscripción + cuota (no pago por llamada). Para el primer acceso a esta API, puedes iniciar una prueba de 7 días o hasta 50 solicitudes; consulta la página del artículo para las opciones de acceso y precios actuales. Después de suscribirte, copia tu clave de API y úsala en el encabezado de Autorización como se muestra a continuación.

Iniciar prueba de 7 días en la API de Datos de Waze

Endpoint de Alertas y Atascos

Este endpoint devuelve alertas y atascos en tiempo real dentro de un área rectangular definida por pares de latitud/longitud de esquina inferior izquierda y esquina superior derecha.

• Método: GET
• URL: https://zylalabs.com/api/4814/waze-data-api/6003/alerts-and-jams
• Parámetros requeridos:
  • bottom_left (string): 51.2800,-0.5100
  • top_right (string): 51.5000,-0.0800
• Parámetros opcionales:
  • max_alerts (string): 100
  • max_jams (string): 0
• Autenticación: Authorization: Bearer YOUR_API_KEY

cURL que puedes copiar

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"

Respuesta de muestra oficial

{
"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": "Cerrado hasta el 31 de julio por trabajos en la carretera. Ref #151583431",
"image": null,
"publish_…

Lo que realmente usarás en la mayoría de las aplicaciones:

• status y request_id para el seguimiento de solicitudes.
• parameters para confirmar que tu cuadro delimitador y límites se aplicaron.
• data.alerts[] para iterar y extraer campos como type, subtype, latitude, longitude, publish_datetime_utc (marca de tiempo UTC), city, street y provider.

Notas que ahorran tiempo:

• Las coordenadas son grados decimales con el orden latitude,longitude en cadenas (por ejemplo, "51.2800,-0.5100").
• publish_datetime_utc está en UTC. Convierte en el borde si tu interfaz de usuario muestra horas locales.
• Cuando max_jams=0 no recibirás atascos; establece un valor positivo para incluirlos si es necesario.
• Si estás haciendo polling, almacena en caché por cuadro delimitador y añade un TTL corto para controlar el uso de la cuota.

Ejemplo en Python: obtener alertas y mapearlas

Este ejemplo llama al endpoint de Alertas y Atascos, analiza la respuesta e imprime una línea compacta por alerta. Reemplaza YOUR_API_KEY con tu clave de 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}")

Endpoint de Direcciones de Conducción

Utiliza esto cuando necesites rutas de Waze y las alertas a lo largo de cada ruta.

• Método: GET
• URL: https://zylalabs.com/api/4814/waze-data-api/6004/driving-directions
• Parámetros requeridos:
  • source_coordinates (string): 32.0852999,34.78176759999999
  • destination_coordinates (string): 32.7940463,34.989571
• Autenticación: Authorization: Bearer YOUR_API_KEY

Lo que devuelve a un alto nivel: un array de rutas candidatas con metadatos como route_name, length_meters, duration_seconds, y una lista de alertas con type, subtype, latitude y longitude para cada ruta. El endpoint admite establecer la hora de llegada deseada según la descripción; consulta la página de la API para las opciones de parámetros actualmente expuestas en el Hub.

Patrones del mundo real que se implementan

• Superposiciones de incidentes para tableros de operaciones: Realiza polling al endpoint de Alertas y Atascos en una cuadrícula fija alrededor de tu área de servicio. Elimina duplicados de alertas por alert_id y expíralas por publish_datetime_utc.
• Alertas geocercadas: Cuando vehículos o mensajeros ingresan a un cuadro delimitador cerca de un cierre, llama al endpoint una vez y envía una notificación concisa usando type/subtype y street (cuando esté disponible).
• Validación de ruta antes del despacho: Llama a Direcciones de Conducción para obtener rutas candidatas e inspecciona la lista de alertas incrustadas para elegir la ruta más rápida que evite peligros o cierres.
• Detección de cambios: Compara respuestas consecutivas por alert_id y num_thumbs_up para detectar incidentes recién confirmados sin recomputar tu capa de mapa completa.

Trabajando con coordenadas y cuadros delimitadores

• bottom_left y top_right son cadenas "lat,lon". Mantén el orden como latitud primero, longitud segundo.
• Asegúrate de que tu cuadro no esté invertido; la latitud aumenta hacia el norte, la longitud aumenta hacia el este.
• Para ciudades grandes, divide el área en mosaicos para mantener los tamaños de resultado predecibles y para paralelizar el polling.
• Persiste los parámetros que usaste (la API los devuelve bajo parameters) para auditar tu canal de ingesta.

Llamando a la API desde agentes de IA a través de MCP

Si estás orquestando con un cliente compatible con MCP (por ejemplo, Claude Code, Cursor, Windsurf), puedes invocar los mismos endpoints HTTPS a través de la puerta de enlace MCP del mercado. Proporciona tu clave de API de Zyla y haz que el agente llame a las URL de los endpoints documentados arriba. La puerta de enlace está disponible en:

MCP

Consejos prácticos:

• Mantén el encabezado Authorization: Bearer YOUR_API_KEY en la definición de la herramienta o en los encabezados por llamada.
• Pasa los parámetros de consulta exactamente como se muestra (cadenas para pares de coordenadas).
• Al construir un bucle autónomo, aplica un retroceso o TTL para respetar tu cuota.

Guía operativa

• El formato del encabezado de autenticación es estricto: Authorization: Bearer YOUR_API_KEY.
• Las marcas de tiempo son UTC. Convierte del lado del cliente según sea necesario.
• Máximos: Usa max_alerts y max_jams para limitar los tamaños de carga útil para clientes móviles o funciones sin servidor con poca memoria.
• Manejo de errores: Siempre verifica el estado de nivel superior y guarda request_id para los registros. En resultados no OK, registra la carga útil completa para soporte.
• Almacenamiento en caché: Para mosaicos de mapa, un TTL corto (por ejemplo, 30–90 segundos) equilibra la frescura y la eficiencia de la cuota.

Flujo de ejemplo de extremo a extremo

1. Elige un cuadro delimitador que cubra tu corredor objetivo (por ejemplo, un buffer de 5 km de una ruta de entrega).
2. Llama a Alertas y Atascos con tu cuadro y límites para alertas y atascos.
3. Renderiza marcadores coloreados por tipo/subtipo de alerta. Muestra publish_datetime_utc en la interfaz de usuario con conversión local y una “edad” relativa.
4. Si aparece un tipo crítico (ROAD_CLOSED) por delante, opcionalmente llama a Direcciones de Conducción para reevaluar el camino.
5. Repite en un bucle cronometrado con almacenamiento en caché tipo ETag en tu capa, indexado por alert_id.

Lista de verificación de solución de problemas

• 401 No autorizado: Verifica que el encabezado de Autorización esté configurado y que la clave sea de la API de Datos de Waze suscrita en Zyla Hub.
• Array de alertas vacío: Confirma que tu cuadro delimitador realmente interseca redes viales; intenta expandir el área o eliminar límites estrictos.
• Visualización de tiempo incorrecta: Recuerda que publish_datetime_utc está en UTC; convierte en el cliente.
• Cargas útiles grandes: Reduce max_alerts y habilita un paginado tipo mosaico dividiendo el cuadro delimitador.

FAQ

¿Qué autenticación utiliza esta API?
Usa el encabezado HTTP Authorization: Bearer YOUR_API_KEY en cada solicitud.

¿Cómo configuro el área geográfica?
Proporciona dos cadenas: bottom_left y top_right, cada una como "lat,lon" (latitud primero, longitud segundo). La API devuelve alertas y atascos dentro del rectángulo.

¿Puedo limitar el número de resultados?
Sí. Usa max_alerts y max_jams para limitar el número de elementos devueltos.

¿El endpoint de Direcciones de Conducción incluye incidentes?
Sí. Incluye alertas a lo largo de cada posible ruta en la respuesta, junto con metadatos de ruta como length_meters y duration_seconds.

¿Hay un plan gratuito?
No hay plan gratuito. Esta API utiliza un modelo de suscripción + cuota. Puedes iniciar una prueba de 7 días o hasta 50 solicitudes en la página del artículo; consulta la lista para las opciones de acceso actuales.

¿Listo para integrar alertas y atascos al nivel de Waze sin construir un canal de datos desde cero? Suscríbete y obtén tu clave en la lista del mercado: Iniciar prueba de 7 días en la API de Datos de Waze. Construye con una clave a través de miles de APIs en Zyla API Hub y entrega tu integración esta semana.