Documentação API

API pública do Azaguas.

Endpoints REST + JSON para integrar dados de risco hídrico em ferramentas externas. Sem autenticação para os endpoints públicos. Cache 60s via ISR. Rate-limit informal: máximo razoável ~60 req/min · 1000 req/h.

Endpoints públicos · sem auth

GET/api/forecast

Snapshot completo: 22 concelhos com risk actual + 72h forecast horário + tempestades activas + sismos recentes.

curl https://azaguas.cv/api/forecast

Estrutura de resposta

{
  generatedAt: "2026-05-01T00:00:00.000Z",
  concelhos: [{
    slug: "praia", name: "Praia", ilha: "Santiago",
    centroidLat: 14.917, centroidLon: -23.508, populacao: 159000,
    currentRisk: { level: "green", confidence: 0.85, ... } | null,
    samples: [{ validFrom, precipMm, windKmh, gustKmh, tempC }, ...],
    marineSamples: [{ validFrom, waveHeightM, ... }, ...]
  }, ...],
  activeStorms: [...],
  recentSeismic: [...]
}

GET/api/decisor
Export CSV dos 22 concelhos com nível, métricas 24h, confiança e timestamps. Para Proteção Civil e ferramentas externas (Excel, R, Python).
```
curl https://azaguas.cv/api/decisor -o azaguas.csv
```
Estrutura de resposta
```
CSV: slug,nome,ilha,populacao,nivel,nivel_anterior,vento_max_24h_kmh,chuva_24h_mm,confianca,calculado_em
```
GET/api/concelhos/[slug]
Detalhe de um concelho específico: risk actual, forecast 72h, histórico 7d.
```
curl https://azaguas.cv/api/concelhos/praia
```
GET/api/health
Health check para uptime monitoring (Better Uptime, Pingdom). Verifica BD com round-trip mínimo.
```
curl https://azaguas.cv/api/health
```
Estrutura de resposta
```
{ status: "ok" | "error", db: "ok" | "down", latencyMs, ts }
```

Embed · iframe

iframe/embed/concelho/[slug]
Widget HTML 320×180 com nome do concelho + risco actual + métricas 24h. Designed para incorporar em sites de câmaras municipais ou jornais. Suporta ?lang=pt|kea.
```
<iframe src="https://azaguas.cv/embed/concelho/praia" width="320" height="180" frameborder="0"></iframe>
```

Cron jobs · Bearer token

Todos os endpoints /api/cron/* exigem Authorization: Bearer $CRON_SECRET. Em produção são disparados por QStash schedules (Upstash) ou via curl manual.

POST/api/cron/forecastPull Open-Meteo Forecast 72h × 22 concelhos + recalcula risk_scores.
POST/api/cron/nowcastPull Open-Meteo Nowcast (precip 15-min) × 22 concelhos.
POST/api/cron/marinePull Open-Meteo Marine wave forecast 72h × 22 concelhos.
POST/api/cron/nhcPull NOAA NHC tempestades tropicais activas Atlântico.
POST/api/cron/seismicPull USGS sismos ≥M2.5 num bbox de ~400 km de Cabo Verde.
POST/api/cron/climatologyPull NASA POWER climatologia mensal 1991-2020 normals (semanal).
POST/api/cron/firesPull NASA FIRMS focos de incêndio VIIRS NRT (estação seca). Requer NASA_FIRMS_KEY.

Termos de uso

Atribuição: Em produtos derivados, indica fonte comoAzaguas · azaguas.cve link para a página de concelho relevante.
Não substitui INMG/SNPCB: Em situações de emergência real, a referência operacional é sempre o INMG (avisos meteorológicos) e SNPCB (Proteção Civil · 132).
Open data: Dados ingeridos de Open-Meteo, NOAA, NASA, USGS — ver fontes. Reuso permitido nos termos das licenças originais.
Sem SLA formal: Serviço cívico com best-effort. Para integrações críticas, implementa retries e fallback para INMG.

Metodologia →← Vista nacional