API de Meteorologia — previsões a 15 dias do ECMWF, ICON, HRRR e AROME

Os mesmos 120 km de costa, como cada modelo os vê 28 km a baía desapareceu 1.3 km a ilha existe

A resolução não é um detalhe de ficha técnica. Decide se uma baía, um vale ou uma ilha existem sequer no modelo — e uma célula que faz a média entre mar e terra dá-lhe a temperatura de nenhum dos dois.

8 modelos, resolvidos automaticamente

Nunca escolhe um modelo. Envia uma coordenada; a API toma o mais fino que a cobre, combina nas fronteiras de domínio para o valor não saltar, e diz-lhe na resposta qual modelo respondeu.

Modelos meteorológicos, resolução, cobertura, passagens e prazo
Modelo	Resolução	Cobertura	Passagens	Prazo	Disponível após
Météo-France AROME	1.3 km	França e arredores	8 ×/dia	51 h	4 h
DWD ICON-D2	2.2 km	Europa Central	4 ×/dia	48 h	2 h
NOAA HRRR	3 km	Estados Unidos continentais	4 ×/dia	48 h	1.5 h
DWD ICON-EU	6.5 km	Europa, Norte de África, Médio Oriente	2 ×/dia	120 h	3 h
DWD ICON	13 km	Mundo	2 ×/dia	180 h	4 h
ECMWF IFS	28 km	Mundo — sempre presente	2 ×/dia	240 h	7 h
ECMWF AIFS	28 km	Mundo, dias 11–15	2 ×/dia	360 h	7 h
ECMWF wave	28 km	Apenas oceanos e mares	2 ×/dia	240 h	7 h

Fronteiras de domínio

Nenhuma costura onde um modelo acaba

Mudar de modelo de repente numa fronteira faz duas localidades vizinhas divergirem sem razão física. Cada domínio traz uma margem de mistura: perto da borda o peso do modelo fino decai e o resto passa para o seguinte. Dentro do domínio recebe o modelo fino puro.

Prazo

Fino ao início, global depois

O AROME para às 51 horas e o HRRR às 48. Depois disso o resolvedor desce por ICON-EU e ICON até ao ECMWF, no mesmo pedido. A sua série de sete dias é cosida com o melhor modelo em cada passo, e a resposta regista a mistura.

O que volta

45 campos horários — 27 armazenados, 18 calculados na hora. 21 vêm por omissão; indique os restantes em hourly=, ou indique menos e reduza a resposta.

Temperatura e humidade

temperature_2m, máximas e mínimas diárias, dewpoint_2m, humidade relativa, temperatura aparente, índice de calor, sensação de frio pelo vento, temperatura de superfície.

Vento

Componentes u/v a 10 m e 100 m para o mercado eólico, velocidade, direção, ponto cardeal, força Beaufort e wind_gust_10m.

Precipitação

Precipitação total descumulada por intervalo, neve como equivalente em água, e um código OMM precipitation_type que separa chuva, neve e chuva gelada.

Nebulosidade e visibilidade

Cobertura total mais baixa, média e alta em separado — a nuvem baixa é o que torna um dia cinzento, o cirro mal atenua o sol. Oitavos para a aviação e visibility para o nevoeiro.

Radiação e sol

Irradiância de onda curta, separada em direta e difusa para o rendimento fotovoltaico. Elevação e azimute do sol, indicador de dia, nascer e pôr do sol, e um índice UV estimado.

Pressão e instabilidade

Pressão ao nível do mar e à superfície, tendência de três horas, cape para o potencial convectivo e vapor de água integrado na coluna.

Solo

Temperatura do solo à superfície e na zona radicular 7–28 cm — a que interessa à agricultura — a partir do ICON. soil_temperature_0cm e soil_temperature_8cm.

Neve

Espessura, equivalente em água, nível de congelamento e snow_line_altitude — a altitude acima da qual a precipitação cai como neve, o que é uma decisão sobre a qual uma autoridade rodoviária pode agir.

Síntese

Um único weather_code OMM por passo de tempo, para o cliente desenhar um ícone em vez de reimplementar a lógica que transforma sete campos em «chuva fraca».

Duas correções que a maioria das API salta

Altitude

A montanha do modelo não é a sua montanha

Um modelo numérico alisa o relevo à sua malha. Uma aldeia de fundo de vale pode estar 400 m abaixo da altitude que o modelo lhe atribui, e a temperatura bruta erra pelo gradiente térmico sobre essa diferença.

Envie elevation com o pedido e o valor é corrigido contra a orografia do próprio modelo. Em zona de relevo isso vale tipicamente 1–3 °C. A resposta indica a altitude do modelo, a sua e o desvio aplicado — pode auditá-lo ou ignorá-lo.

Frescura

Desatualizado ganha a ausente, e di-lo

Se a nossa passagem mais recente for mais velha do que o esperado, continua a receber dados, com "stale": true e data_age_hours no bloco source. Uma previsão com oito horas é mais útil aos seus utilizadores do que um erro 500.

O que nunca recebe é um número desatualizado com ar de fresco. Decida no seu próprio código se o mostra, avisa ou recorre a outra coisa.

{
  "grid": { "distance_km": 8.04, "resolution_km": 28.0 },
  "elevation": {
    "applied": true,
    "model_elevation_m": 91.0,
    "location_elevation_m": 113,
    "temperature_offset_c": -0.14
  },
  "source": {
    "model": "ecmwf_ifs",
    "model_run": "20260725T00Z",
    "data_age_hours": 8.95,
    "stale": false,
    "attribution": "Data: ECMWF (CC-BY-4.0)"
  }
}

Na mesma chave, não noutra fatura

Quatro coisas que noutros sítios são normalmente produtos separados. Aqui são pontos de entrada do plano que já comprou.

/v1/probability

Qual é a confiança da previsão?

Um valor único diz 22 °C na quinta-feira — um palpite apresentado como facto. Isto devolve p10, p50, p90 e a dispersão do conjunto de 50 membros do ECMWF, mais as probabilidades de chuva a 0,1, 1, 5 e 10 mm.

Uma dispersão de 0,4 °C é uma situação assente. Uma dispersão de 3 °C significa que é a própria atmosfera que está incerta, e os seus utilizadores merecem sabê-lo.

/v1/air-quality

Partículas, ozono, NO₂ — e poeiras do Sara

Do Copernicus CAMS, com os valores-guia da OMS em cada resposta, para que um número possa ser situado sem ir procurá-lo.

A poeira conta no Norte de África e no Mediterrâneo: um episódio leva as PM10 acima de mil µg/m³ durante dias, e os serviços gratuitos para o público cobrem-no mal.

/v1/marine

Estado do mar em todo o mundo

Altura significativa da onda, direção e período do modelo de ondas do ECMWF, até dez dias. Um ponto em terra devolve 404 not_at_sea em vez de uma coluna de nulos que parece uma avaria.

/v1/hydrology

Quanta água chega aqui

Caudal fluvial do Copernicus GloFAS numa rede de rios de 0,05° — não quanta chuva cai a montante, mas quanta água chega a este ponto, que uma bacia e um dia de percurso separam.

Apenas informativo. Emitir avisos de cheia está reservado às autoridades nacionais e regionais.

Onde vai trabalhar

Produtos de meteorologia

Páginas de cidade, aplicações e widgets. Um código OMM por passo para o ícone, agregados diários cortados no fuso do utilizador, e um catálogo de cidades com pesquisa e ponto mais próximo.

Energia

Vento a 100 m para a altura do cubo, irradiância direta e difusa para o rendimento fotovoltaico, e dispersão de conjunto para o lado do risco de uma posição.

Agricultura

Temperatura e temperatura do solo a quatro profundidades, entradas de evapotranspiração, risco de geada a partir da temperatura mínima, e rajadas para janelas de tratamento.

Logística e estradas

Cota de neve, nível de congelamento, tipo de precipitação e visibilidade — os quatro campos que decidem se um desfiladeiro fecha.

Náutica e ar livre

Altura, período e direção da onda, rajadas, índice UV e horas de luz para o planeamento que tem de acontecer com uma semana de antecedência.

Revendedores

Pode redistribuir. Construa um produto por cima e venda-o, com uma linha de atribuição no rodapé como única obrigação que o acompanha.

O que faz mal

Preferimos que conheça os limites agora a que os descubra em produção.

Forte

Temperatura, pressão, vento sinóptico, humidade, insolação. O erro típico da temperatura a 2 m às 24 horas ronda 1–1,5 °C. O ECMWF é o melhor modelo determinístico global do mundo, e é o que recebe.

Fraco

Trovoadas convectivas — uma célula de 28 km não resolve uma trovoada, e nem 3 km fazem mais do que insinuá-la. Localização e hora exatas dos aguaceiros. Microclima costeiro e de montanha abaixo da resolução do modelo. Brisas marítimas e bolsas de ar frio em vales, que a correção de altitude não modela.

Honestidade geográfica

Em França, na Alemanha, nos Estados Unidos e no Canadá servimos modelos nacionais a 1,3–3 km e uma aldeia pequena tem mesmo a sua própria célula. Os territórios ultramarinos, o Alasca, o Havai e o norte do Canadá ficam fora desses domínios e recaem em 13 km. No resto da Europa tem 6,5 km. Em África, no Médio Oriente e em boa parte da Ásia o melhor modelo público disponível é de 13–28 km: obtém o tempo da zona em vez do da rua. A correção de altitude reduz essa distância; não a fecha.

Não é um serviço de avisos

Sem alertas, sem cores de nível, sem instruções para agir. Isso pertence às autoridades, que também podem cortar uma estrada e evacuar uma aldeia.

Perguntas frequentes

Que modelo servirá a minha localização?

O mais fino que a cobre: AROME a 1,3 km em França, ICON-D2 a 2,2 km na Europa Central, HRRR a 3 km nos Estados Unidos, ICON-EU a 6,5 km sobre a Europa e o Norte de África, ICON a 13 km no mundo, e ECMWF IFS a 28 km como base sempre presente.

Chame /v1/models para ver o registo atual e o domínio de cada modelo, ou leia source.model em qualquer resposta.

Com que frequência é atualizada?

Os modelos globais duas vezes por dia às 00 e 12 UTC; os modelos nacionais de alta resolução quatro vezes por dia às 00, 06, 12 e 18 UTC. Os dados tornam-se utilizáveis entre 90 minutos e 7 horas depois da hora da passagem consoante o fornecedor — a tabela acima indica cada um.

As respostas de previsão ficam cinco minutos em cache na periferia, o que absorve o tráfego repetido das páginas de cidade sem nunca servir uma passagem anterior à que temos.

Posso pedir muitos locais de uma vez?

Uma coordenada por pedido. O armazenamento está dividido em blocos de modo a que toda a série temporal de uma área pequena caiba num bloco — um ponto ao longo de todos os passos é a consulta barata, e é a que praticamente qualquer produto faz de facto.

Para tráfego em forma de cidade, /v1/forecast/city/{country}/{slug} traz o fuso horário e a altitude da cidade, para que não tenha de o fazer.

Existe descarga em massa?

Não, em nenhum plano. O arquivo é aquilo que está a pagar, e uma exportação sem limite é a forma como um concorrente o adquire numa tarde. A exportação CSV de graus-dia existe e é deliberadamente limitada.

Quanto custa?

Grátis para 10000 créditos por mês sem cartão. 19 € por mês para 50 000 créditos incluindo a API de Graus-dia, histórico e CSV. 79 € para 400 000 créditos e tudo o resto. Um pedido de previsão vale um crédito.

Preços completos →

Experimente com as suas próprias coordenadas

O plano gratuito devolve os mesmos dados dos pagos. Aponte-o a um sítio que conheça bem e julgue os números você mesmo.

Obter uma chave gratuita Referência do ponto de previsão

O modelo mais fino que cobre o seu ponto. Escolhido a cada pedido.