Wildfire.pt — API Pública

Name: Wildfire.pt
Author: Wildfire.pt

Referência completa dos endpoints

A API Wildfire.pt disponibiliza acesso em tempo real a dados de deteção de incêndios florestais em Portugal, combinando dados de satélites NASA, modelos de IA e informação meteorológica do IPMA.

Pensada para operacionais, municípios e sistemas de proteção civil. Gratuita e open-source.

Latência

< 500ms

Uptime

99.9%

Atualização

15 min

Base URL

https://api.wildfire.pt

Todos os endpoints começam com /v1/. Versões anteriores são mantidas durante 6 meses após nova versão.

Autenticação

Podes usar a API sem autenticação (tier público), mas com limites mais restritos. Para limites maiores, pede uma API key gratuita.

Sem API Key

Acesso público imediato

• 60 pedidos / minuto
• Dados com atraso de 5 min
• Sem acesso ao histórico

Com API Key

Gratuita — registo simples

• 1.000 pedidos / minuto
• Dados em tempo real
• Histórico completo + WebSocket

Enviar a API key via cabeçalho (recomendado):

curl https://api.wildfire.pt/v1/fires \
  -H "X-API-Key: wf_sua_api_key_aqui"

Alternativa: query param ?api_key=wf_... (não recomendado para produção).

Rate Limits

Os limites são por IP (sem key) ou por API key. Os cabeçalhos de resposta informam o estado atual.

Tier	Pedidos/min	Pedidos/dia	Histórico	WebSocket
Público (sem key)	60	5.000	—	—
Gratuito (com key)	1.000	100.000	30 dias	Sim
Parceiro (com key)	Ilimitado	Ilimitado	Completo	Sim

Cabeçalhos de rate limit nas respostas:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 987
X-RateLimit-Reset: 1710000060
Retry-After: 30  # apenas quando 429

Códigos de Erro

A API usa códigos HTTP standard. Todos os erros têm o mesmo formato JSON.

Código	Significado	Causa comum
200	OK	Pedido processado com sucesso
400	Bad Request	Parâmetros inválidos ou em falta
401	Unauthorized	API key inválida ou expirada
403	Forbidden	Sem permissão para este recurso
404	Not Found	Recurso não encontrado
429	Too Many Requests	Rate limit excedido
500	Internal Server Error	Erro interno — reportar no GitHub
503	Service Unavailable	Manutenção ou fonte de dados indisponível

Formato de erro:

{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "O parâmetro 'confidence' deve ser: low | medium | high | all",
    "status": 400,
    "timestamp": "2026-03-14T10:30:00Z"
  }
}

Listar Incêndios Ativos

GET/v1/fires

Devolve os incêndios detetados nas últimas 24 horas em Portugal Continental e Ilhas, com filtragem por confiança, fonte e área geográfica.

Query Parameters

Parâmetro	Tipo	Req.	Descrição
`confidence`	`string`	Não	Nível de confiança da deteção.padrão: allex: high
`source`	`string`	Não	Fonte dos dados: nasa \| anepc \| model \| all.padrão: all
`limit`	`integer`	Não	Número de resultados por página (1–500).padrão: 100
`page`	`integer`	Não	Número da página para paginação.padrão: 1
`bbox`	`string`	Não	Bounding box: min_lng,min_lat,max_lng,max_lat.ex: -9.6,36.8,-6.0,42.2
`since`	`string (ISO 8601)`	Não	Devolve apenas incêndios detetados após esta data/hora.ex: 2026-03-14T00:00:00Z

Exemplo

curl "https://api.wildfire.pt/v1/fires?confidence=high&limit=10" \
  -H "X-API-Key: wf_sua_api_key_aqui"

Resposta

{
  "fires": [
    {
      "id": "nasa-viirs-20260314-001",
      "lat": 39.5431,
      "lng": -8.1372,
      "brightness": 342.7,
      "confidence": 92,
      "confidence_label": "high",
      "frp": 18.4,
      "source": "nasa",
      "satellite": "VIIRS C2 (Suomi-NPP)",
      "acq_date": "2026-03-14",
      "acq_time": "10:24",
      "detected_at": "2026-03-14T10:24:00Z",
      "region": "Santarém",
      "district": "Santarém",
      "municipality": "Torres Novas",
      "area_ha": null,
      "status": "active"
    }
  ],
  "meta": {
    "total": 3,
    "page": 1,
    "limit": 10,
    "pages": 1,
    "updated_at": "2026-03-14T10:30:00Z"
  }
}

Detalhe de Incêndio

GET/v1/fires/{id}

Retorna informação detalhada sobre um incêndio específico, incluindo histórico de deteções, previsão de propagação e dados meteorológicos associados.

Path Parameters

Parâmetro	Tipo	Req.	Descrição
`id`	`string`	Sim	ID único do incêndio.ex: nasa-viirs-20260314-001

Exemplo

curl "https://api.wildfire.pt/v1/fires/nasa-viirs-20260314-001" \
  -H "X-API-Key: wf_sua_api_key_aqui"

Resposta

{
  "fire": {
    "id": "nasa-viirs-20260314-001",
    "lat": 39.5431,
    "lng": -8.1372,
    "brightness": 342.7,
    "confidence": 92,
    "confidence_label": "high",
    "frp": 18.4,
    "source": "nasa",
    "detected_at": "2026-03-14T10:24:00Z",
    "last_seen_at": "2026-03-14T10:24:00Z",
    "status": "active",
    "region": "Santarém",
    "propagation": {
      "direction": "NE",
      "speed_kmh": 3.2,
      "risk_score": 7.4,
      "predicted_area_1h_ha": 12.0
    },
    "weather": {
      "temperature_c": 28.4,
      "humidity_pct": 22,
      "wind_speed_kmh": 18,
      "wind_direction": "SW",
      "fwi": 32.1
    }
  }
}

Histórico de Incêndios

GET/v1/fires/history

Requer API key. Gratuita mas com registo.

Acesso ao histórico de incêndios detetados. Útil para análise de padrões, relatórios e modelos preditivos.

Query Parameters

Parâmetro	Tipo	Req.	Descrição
`start_date`	`string (ISO 8601)`	Sim	Data de início do intervalo.ex: 2026-01-01
`end_date`	`string (ISO 8601)`	Não	Data de fim (padrão: hoje).ex: 2026-03-14
`confidence`	`string`	Não	Filtro por confiança: low \| medium \| high \| all.padrão: all
`source`	`string`	Não	Fonte: nasa \| anepc \| model \| all.padrão: all
`bbox`	`string`	Não	Área geográfica: min_lng,min_lat,max_lng,max_lat.
`limit`	`integer`	Não	Resultados por página (1–1000).padrão: 200
`page`	`integer`	Não	Número da página.padrão: 1
`format`	`string`	Não	Formato: json \| csv \| geojson.padrão: json

Exemplo

curl "https://api.wildfire.pt/v1/fires/history?start_date=2026-01-01&confidence=high" \
  -H "X-API-Key: wf_sua_api_key_aqui"

Alertas Ativos

GET/v1/alerts

Retorna alertas de risco de incêndio ativos, combinando dados meteorológicos (IPMA), índice FWI e deteções por satélite.

Query Parameters

Parâmetro	Tipo	Req.	Descrição
`level`	`string`	Não	Nível do alerta: low \| medium \| high \| critical \| all.padrão: all
`region`	`string`	Não	Filtrar por região/distrito.ex: Leiria
`active_only`	`boolean`	Não	Apenas alertas ativos no momento.padrão: true

Resposta

{
  "alerts": [
    {
      "id": "alert-20260314-leiria-01",
      "level": "high",
      "level_label": "Alto",
      "region": "Leiria",
      "title": "Risco elevado de incêndio — Leiria",
      "message": "Temperatura acima de 30°C, humidade abaixo de 20% e vento forte.",
      "fwi": 38.2,
      "issued_at": "2026-03-14T08:00:00Z",
      "expires_at": "2026-03-14T20:00:00Z",
      "source": "ipma+model"
    }
  ],
  "meta": { "total": 2, "updated_at": "2026-03-14T10:30:00Z" }
}

Risco por Localização

GET/v1/risk

Calcula o índice de risco de incêndio para um ponto geográfico específico, agregando fatores meteorológicos, histórico e deteções recentes.

Query Parameters

Parâmetro	Tipo	Req.	Descrição
`lat`	`float`	Sim	Latitude (Portugal: 36.8 a 42.2).ex: 39.54
`lng`	`float`	Sim	Longitude (Portugal: -9.6 a -6.0).ex: -8.14

Exemplo

curl "https://api.wildfire.pt/v1/risk?lat=39.54&lng=-8.14" \
  -H "X-API-Key: wf_sua_api_key_aqui"

Resposta

{
  "risk": {
    "lat": 39.54,
    "lng": -8.14,
    "score": 7.4,
    "label": "Alto",
    "color": "#ef4444",
    "fwi": 32.1,
    "factors": {
      "temperature_c": 28.4,
      "humidity_pct": 22,
      "wind_speed_kmh": 18,
      "wind_direction": "SW",
      "vegetation_dryness": "high",
      "recent_fires_nearby": 1
    },
    "calculated_at": "2026-03-14T10:30:00Z"
  }
}

Regiões

GET/v1/regions

Retorna todos os distritos de Portugal Continental e Ilhas com o índice de risco atual e estatísticas de incêndios ativos.

Query Parameters

Parâmetro	Tipo	Req.	Descrição
`min_risk`	`float`	Não	Filtrar regiões com score mínimo (0–10).ex: 5.0
`sort`	`string`	Não	Ordenar por: risk_score \| name \| active_fires.padrão: risk_score
`order`	`string`	Não	Direção: asc \| desc.padrão: desc

Resposta

{
  "regions": [
    {
      "id": "leiria",
      "name": "Leiria",
      "type": "district",
      "risk_score": 8.1,
      "risk_label": "Muito Alto",
      "active_fires": 2,
      "area_km2": 3517,
      "centroid": { "lat": 39.74, "lng": -8.81 },
      "updated_at": "2026-03-14T10:30:00Z"
    }
  ],
  "meta": { "total": 20, "updated_at": "2026-03-14T10:30:00Z" }
}

Estatísticas

GET/v1/stats

Resumo estatístico do sistema: incêndios ativos, totais históricos, performance do modelo e estado das fontes de dados.

Query Parameters

Parâmetro	Tipo	Req.	Descrição
`period`	`string`	Não	Período: today \| 7d \| 30d \| year \| all.padrão: today

Resposta

{
  "stats": {
    "period": "today",
    "fires": {
      "total": 3,
      "high_confidence": 2,
      "medium_confidence": 1,
      "low_confidence": 0,
      "by_source": { "nasa": 3, "anepc": 0, "model": 0 }
    },
    "alerts": { "active": 2, "critical": 0, "high": 2 },
    "model": {
      "accuracy": 0.94,
      "false_positive_rate": 0.03,
      "avg_detection_lead_min": 42
    },
    "sources": {
      "nasa_firms": { "status": "online", "last_update": "2026-03-14T10:24:00Z" },
      "ipma": { "status": "online", "last_update": "2026-03-14T10:00:00Z" }
    },
    "updated_at": "2026-03-14T10:30:00Z"
  }
}

Meteorologia

GET/v1/weather

Dados meteorológicos atuais e previsão para as próximas 24 horas, com ênfase nos fatores de risco de incêndio (temperatura, humidade, vento, FWI).

Query Parameters

Parâmetro	Tipo	Req.	Descrição
`lat`	`float`	Sim	Latitude.ex: 39.54
`lng`	`float`	Sim	Longitude.ex: -8.14
`forecast`	`boolean`	Não	Incluir previsão para 24h.padrão: false

Resposta

{
  "weather": {
    "lat": 39.54,
    "lng": -8.14,
    "current": {
      "temperature_c": 28.4,
      "humidity_pct": 22,
      "wind_speed_kmh": 18,
      "wind_direction": "SW",
      "wind_gust_kmh": 32,
      "precipitation_mm": 0,
      "fwi": 32.1,
      "fwi_label": "Alto"
    },
    "source": "ipma",
    "updated_at": "2026-03-14T10:00:00Z"
  }
}

WebSocket — Tempo Real

WSwss://api.wildfire.pt/v1/ws

Requer API key. Gratuita mas com registo.

Ligação

wss://api.wildfire.pt/v1/ws?api_key=wf_sua_api_key_aqui

Subscrição de eventos

Após ligar, envia uma mensagem JSON para subscrever os eventos pretendidos:

{
  "action": "subscribe",
  "events": ["fire.new", "fire.updated", "alert.new", "alert.updated"],
  "filters": {
    "confidence": "high",
    "bbox": [-9.6, 36.8, -6.0, 42.2]
  }
}

Tipos de eventos

Evento	Descrição
`fire.new`	Novo incêndio detetado
`fire.updated`	Incêndio existente atualizado (confiança, área, etc.)
`fire.resolved`	Incêndio marcado como extinto
`alert.new`	Novo alerta emitido
`alert.updated`	Alerta atualizado
`alert.expired`	Alerta expirado
`ping`	Heartbeat do servidor (a cada 30s)

Exemplo completo

const ws = new WebSocket(
  "wss://api.wildfire.pt/v1/ws?api_key=wf_sua_api_key_aqui"
);

ws.onopen = () => {
  ws.send(JSON.stringify({
    action: "subscribe",
    events: ["fire.new", "alert.new"],
    filters: { confidence: "high" },
  }));
};

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  if (msg.type === "fire.new") {
    console.log("Novo incêndio!", msg.data);
  } else if (msg.type === "alert.new") {
    console.log("Novo alerta!", msg.data);
  }
};

ws.onclose = () => setTimeout(() => location.reload(), 3000); // reconnect

Formato de mensagem recebida

{
  "type": "fire.new",
  "timestamp": "2026-03-14T10:24:00Z",
  "data": {
    "id": "nasa-viirs-20260314-001",
    "lat": 39.5431,
    "lng": -8.1372,
    "confidence": 92,
    "confidence_label": "high",
    "frp": 18.4,
    "source": "nasa",
    "region": "Santarém",
    "detected_at": "2026-03-14T10:24:00Z"
  }
}

Reconnect automático

Implementa sempre reconnect com exponential backoff. O servidor pode encerrar a ligação após 5 minutos de inatividade ou durante manutenção. Usa o evento ping como heartbeat para detetar desligamentos.

API em desenvolvimento

Esta documentação define os endpoints planeados. A API será disponibilizada publicamente assim que o sistema estiver em produção.

Acompanhar no GitHub