API para alertas e congestionamentos

Sua equipe precisa de alertas de incidentes e congestionamentos em tempo real no estilo Waze em uma área específica, e você precisa de um endpoint que possa ser enviado esta semana. Ao final deste artigo, você irá consultar uma API real que retorna alertas e congestionamentos do Waze para uma caixa delimitadora, analisar a resposta e entender como usá-la tanto do seu backend quanto de agentes de IA via MCP.

O que você pode construir com esta API

A API de Dados do Waze expõe duas capacidades que os desenvolvedores costumam solicitar:

• Alertas e congestionamentos em tempo real em um retângulo geográfico (acidentes, fechamentos de estradas, perigos, polícia, congestionamentos e mais) para que você possa sinalizar incidentes em um mapa, acionar redirecionamentos ou alertar equipes de campo.
• Direções de condução com alertas ao longo das rotas candidatas, permitindo escolha de rotas e fluxos de trabalho sensíveis ao ETA.

Você chamará esses endpoints através de uma única assinatura do Zyla API Hub e chave da API. Nenhuma integração direta com o Waze é necessária.

Começando no Zyla API Hub

Abra a listagem da API de Dados do Waze no Zyla API Hub e assine. O hub utiliza um modelo de assinatura + cota (não pago por chamada). Para o primeiro acesso a esta API, você pode iniciar um teste de 7 dias ou até 50 solicitações—verifique a página do item para opções de acesso e preços atuais. Após assinar, copie sua chave da API e use-a no cabeçalho de Autorização conforme mostrado abaixo.

Iniciar teste de 7 dias na API de Dados do Waze

Endpoint de Alertas e Congestionamentos

Este endpoint retorna alertas e congestionamentos em tempo real dentro de uma área retangular definida por pares de latitude/longitude inferior esquerda e superior direita.

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

cURL que você pode 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"

Resposta de exemplo 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": "Fechado até 31 de jul para obras. Ref #151583431",
"image": null,
"publish_…

O que você realmente usará na maioria dos aplicativos:

• status e request_id para rastreamento de solicitações.
• parameters para confirmar que sua caixa delimitadora e limites foram aplicados.
• data.alerts[] para iterar e extrair campos como tipo, subtipo, latitude, longitude, publish_datetime_utc (timestamp UTC), cidade, rua e provedor.

Notas que economizam tempo:

• As coordenadas são graus decimais com a ordem latitude,longitude em strings (por exemplo, "51.2800,-0.5100").
• publish_datetime_utc está em UTC. Converta na borda se sua interface mostrar horários locais.
• Quando max_jams=0 você não receberá congestionamentos; defina um valor positivo para incluí-los se necessário.
• Se você estiver fazendo polling, armazene em cache por caixa delimitadora e adicione um TTL curto para controlar o uso da cota.

Exemplo em Python: buscar alertas e mapeá-los

Este exemplo chama o endpoint de Alertas e Congestionamentos, analisa a resposta e imprime uma linha compacta por alerta. Substitua YOUR_API_KEY pela sua chave do 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 retornou status não OK: {payload}")

alerts = (payload.get("data") or {}).get("alerts", [])
print(f"recebidos {len(alerts)} alertas")
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 Direções de Condução

Use isso quando você precisar de rotas do Waze e os alertas ao longo de cada rota.

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

O que ele retorna em um nível alto: um array de rotas candidatas com metadados como route_name, length_meters, duration_seconds, e uma lista de alertas com tipo, subtipo, latitude e longitude para cada rota. O endpoint suporta a definição do horário de chegada desejado conforme a descrição; consulte a página da API para opções de parâmetros atualmente expostas no Hub.

Padrões do mundo real que funcionam

• Sobreposições de incidentes para painéis de operações: Consulte o endpoint de Alertas e Congestionamentos em uma grade fixa ao redor da sua área de serviço. Remova duplicatas de alertas por alert_id e expire-os por publish_datetime_utc.
• Alertas geofenced: Quando veículos ou mensageiros entram em uma caixa delimitadora próxima a um fechamento, chame o endpoint uma vez e envie uma notificação concisa usando tipo/subtipo e rua (quando disponível).
• Validação de rota antes do despacho: Chame Direções de Condução para buscar rotas candidatas e inspecione a lista de alertas incorporados para escolher a rota mais rápida que evite perigos ou fechamentos.
• Detecção de mudanças: Compare respostas consecutivas por alert_id e num_thumbs_up para detectar incidentes recém-confirmados sem recalcular sua camada de mapa completa.

Trabalhando com coordenadas e caixas delimitadoras

• bottom_left e top_right são strings "lat,lon". Mantenha a ordem como latitude primeiro, longitude segundo.
• Certifique-se de que sua caixa não está invertida; a latitude aumenta para o norte, a longitude aumenta para o leste.
• Para grandes cidades, divida a área em azulejos para manter os tamanhos dos resultados previsíveis e para paralelizar o polling.
• Persista os parâmetros que você usou (a API os ecoa sob parâmetros) para auditar seu pipeline de ingestão.

Chamando a API de agentes de IA via MCP

Se você estiver orquestrando com um cliente compatível com MCP (por exemplo, Claude Code, Cursor, Windsurf), você pode invocar os mesmos endpoints HTTPS através do gateway MCP do marketplace. Forneça sua chave da API Zyla e faça o agente chamar as URLs dos endpoints documentados acima. O gateway está disponível em:

MCP

Dicas práticas:

• Mantenha o cabeçalho Authorization: Bearer YOUR_API_KEY na definição da ferramenta ou nos cabeçalhos por chamada.
• Passe os parâmetros de consulta exatamente como mostrado (strings para pares de coordenadas).
• Ao construir um loop autônomo, imponha um backoff ou TTL para respeitar sua cota.

Orientações operacionais

• O formato do cabeçalho de autenticação é rigoroso: Authorization: Bearer YOUR_API_KEY.
• Os timestamps estão em UTC. Converta do lado do cliente conforme necessário.
• Limites máximos: Use max_alerts e max_jams para limitar os tamanhos dos payloads para clientes móveis ou funções serverless com pouca memória.
• Tratamento de erros: Sempre verifique o status de nível superior e mantenha request_id para logs. Em resultados não OK, registre o payload completo para suporte.
• Cache: Para azulejos de mapa, um TTL curto (por exemplo, 30–90 segundos) equilibra frescor e eficiência de cota.

Fluxo de exemplo de ponta a ponta

1. Escolha uma caixa delimitadora que cubra seu corredor alvo (por exemplo, um buffer de 5 km de uma rota de entrega).
2. Chame Alertas e Congestionamentos com sua caixa e limites para alertas e congestionamentos.
3. Renderize marcadores coloridos por tipo/subtipo de alerta. Mostre publish_datetime_utc na interface com conversão local e uma “idade” relativa.
4. Se um tipo crítico (ROAD_CLOSED) aparecer à frente, chame opcionalmente Direções de Condução para reavaliar o caminho.
5. Repita em um loop temporizado com cache semelhante ao ETag em sua camada, indexado por alert_id.

Lista de verificação de solução de problemas

• 401 Não autorizado: Verifique se o cabeçalho Authorization está definido e se a chave é da API de Dados do Waze assinada no Zyla Hub.
• Array de alertas vazio: Confirme se sua caixa delimitadora realmente intersecta redes rodoviárias; tente expandir a área ou remover limites apertados.
• Exibição de tempo incorreta: Lembre-se de que publish_datetime_utc está em UTC; converta no cliente.
• Payloads grandes: Reduza max_alerts e habilite a paginação como azulejos dividindo a caixa delimitadora.

FAQ

Que autenticação esta API usa?
Use o cabeçalho HTTP Authorization: Bearer YOUR_API_KEY em cada solicitação.

Como eu defino a área geográfica?
Forneça duas strings: bottom_left e top_right, cada uma como "lat,lon" (latitude primeiro, longitude segundo). A API retorna alertas e congestionamentos dentro do retângulo.

Posso limitar o número de resultados?
Sim. Use max_alerts e max_jams para limitar o número de itens retornados.

O endpoint de Direções de Condução inclui incidentes?
Sim. Inclui alertas ao longo de cada possível rota na resposta, juntamente com metadados da rota, como length_meters e duration_seconds.

Há um plano gratuito?
Não há plano gratuito. Esta API usa um modelo de assinatura + cota. Você pode iniciar um teste de 7 dias ou até 50 solicitações na página do item; verifique a listagem para opções de acesso atuais.

Pronto para integrar alertas e congestionamentos no estilo Waze sem construir um pipeline de dados do zero? Assine e obtenha sua chave na listagem do marketplace: Iniciar teste de 7 dias na API de Dados do Waze. Construa com uma chave em milhares de APIs no Zyla API Hub e envie sua integração esta semana.