API Meteorologia

Previsão#

Parâmetros

Resposta

{
  "latitude": 48.85,
  "longitude": 2.35,
  "timezone": "Europe/Paris",
  "grid": {
    "latitude": 48.85, "longitude": 2.35,
    "distance_km": 0.42, "resolution_km": 1.3
  },
  "elevation": {
    "applied": true,
    "model_elevation_m": 91.0,
    "location_elevation_m": 113,
    "temperature_offset_c": -0.14
  },
  "source": {
    "model": "mf_arome",
    "model_run": "20260801T00Z",
    "reference_time": "2026-08-01T00:00:00+00:00",
    "data_age_hours": 3.95,
    "stale": false,
    "attribution": "Data: Météo-France (etalab-2.0)"
  },
  "hourly": {
    "time": ["2026-08-01T00:00:00+02:00", "..."],
    "temperature_2m": [18.1, 17.9, 17.6, "..."],
    "apparent_temperature": [17.4, "..."],
    "weather_code": [0, 1, 2, "..."]
  },
  "daily": {
    "date": ["2026-08-01", "..."],
    "temperature_2m_max": [26.6, "..."],
    "temperature_2m_min": [16.2, "..."],
    "precipitation_sum": [0.0, "..."],
    "uv_index_max": [7.6, "..."],
    "sunrise": ["2026-08-01T06:24:00+02:00", "..."],
    "sunset": ["2026-08-01T21:24:00+02:00", "..."],
    "daylight_hours": [15.0, "..."]
  }
}

Encolher a carga útil

O bloco horário completo para 15 dias são cerca de 32 campos × 360 horas. Se traça três deles, peça três:

GET /v1/forecast?lat=48.85&lon=2.35&days=3
    &hourly=temperature_2m,precipitation,weather_code
    &include_daily=false

O mesmo preço — o custo está em ler o arquivo, não em serializá-lo — mas um décimo dos bytes e visivelmente mais rápido de processar num telemóvel.

Previsão por cidade#

Prefira isto a coordenadas em cru sempre que puder. O catálogo fornece duas coisas que uma coordenada não pode: a altitude verdadeira da cidade, para que a correção de relevo se aplique sem que a forneça, e o seu fuso horário, para que os agregados diários sejam cortados no dia local certo.

GET /v1/forecast/city/dz/alger      # slug francês
GET /v1/forecast/city/dz/algiers    # slug inglês — a mesma cidade
GET /v1/forecast/city/fr/paris

country é um código ISO-3166-1 alfa-2, em minúsculas. O slug ignora acentos: bejaia encontra Béjaïa. Um slug desconhecido devolve 404 city_not_found com um vetor suggestions — mostre-o em vez de um beco sem saída.

Todos os parâmetros de consulta de /v1/forecast continuam a valer, exceto lat, lon e elevation, que o catálogo fornece. Passar timezone substitui o da cidade, o que quase nunca é o que quer.

Condições atuais#

A temperatura, a humidade, o vento e a pressão são interpolados linearmente para o instante presente, entre os dois passos do modelo que o enquadram.

Use isto para mostrar o «agora mesmo». Para qualquer coisa que vá comparar ao longo do tempo, use /v1/forecast e leia a hora que quer: a série é estável, ao passo que o agora mexe-se debaixo dos seus pés entre duas chamadas.

Referência dos campos#

Campos horários

21 destes voltam por omissão. Os restantes são seus por um pedido — nomeie-os em hourly=, separados por vírgulas — e ficam retidos por custo, não por dúvida: cada campo armazenado é uma leitura comprimida separada, por isso uma resposta por omissão a trazer os 45 faria todos pagar pelos poucos que querem a espessura da neve.

GET /v1/forecast?lat=45.19&lon=5.72&hourly=temperature_2m,snow_line_altitude,soil_temperature_8cm

Um campo que um modelo não publica volta como null no troço da previsão desse modelo, em vez de desaparecer da resposta — por isso uma cadeia que começa no AROME e continua no ICON-EU devolve visibility do princípio ao fim, nulo nas primeiras 51 horas. Um nome de campo desconhecido é um 400 unknown_field, com a correspondência mais próxima sugerida; antes era ignorado em silêncio.

Campos diários

date, temperature_2m_max, temperature_2m_min, temperature_2m_mean, precipitation_sum, wind_speed_max, wind_gust_max, shortwave_radiation_sum (MJ/m²), uv_index_max, sunrise, sunset, daylight_hours, weather_code.

Agregados em dias de calendário locais, não em UTC. Um dia parcial em qualquer dos extremos do intervalo é omitido em vez de ser reportado com um máximo enganador — por isso um pedido de 7 dias pode legitimamente devolver 6 linhas diárias.

Modelos e resolução#

Servimos o modelo mais fino que cobre o seu ponto e o seu prazo. Nunca escolhe um; a escolha é reportada em source.model para que saiba sempre qual respondeu.

Os modelos de alta resolução são todos de curto prazo — a 1 km a atmosfera torna-se caótica ao fim de dois dias, pelo que prever mais longe não teria sentido — e a resolução vai portanto descendo à medida que a previsão avança:

dia 0 ─────── dia 2 ─────── dia 5 ───────────────── dia 15
  AROME 1,3 km (França)
  ICON-D2 2,2 km (Alemanha, Alpes, Benelux)
  HRRR 3 km (EUA e sul do Canadá)
              ICON-EU 6,5 km (Europa)
                          ICON 13 km · ECMWF 28 km (global)
                                              AIFS (só tendência)

As transições no limite do domínio de um modelo são fundidas, para que duas localidades de um lado e do outro de uma fronteira nunca discordem por um degrau.

/v1/models não precisa de chave, o que faz dele a coisa certa para consultar a partir de uma página de estado ou para verificar antes de comprar: reporta o run mais recente de cada modelo e a sua idade, pelo que «os dados estão frescos?» tem resposta sem gastar um crédito.

Probabilidades de ensemble#

Uma previsão única diz 22 °C na quinta-feira. Isso é um palpite apresentado como um facto. Este endpoint responde à pergunta sobre a qual decide de facto: qual é a confiança, e qual é a probabilidade de chuva que vale a pena considerar.

É calculado a partir do ensemble do ECMWF — o mesmo modelo corrido 50 vezes a partir de condições iniciais ligeiramente diferentes. Onde as corridas concordam, a previsão é confiante. Onde se dispersam, a própria atmosfera é incerta, e nenhum modelo, por melhor que seja, lhe pode dizer mais.

{
  "members": 50,
  "hourly": {
    "time": ["2026-08-01T00:00:00+00:00"],
    "temperature_2m_p10": [26.4],
    "temperature_2m_p50": [26.78],
    "temperature_2m_p90": [27.3],
    "temperature_2m_spread": [0.4],
    "precipitation_probability_0_1mm": [10.0],
    "precipitation_probability_1_0mm": [0.0],
    "precipitation_probability_5_0mm": [0.0],
    "precipitation_probability_10_0mm": [0.0],
    "precipitation_p90": [0.1]
  }
}

Como se lê

p10 e p90 enquadram os 80 % centrais dos membros: um em cada dez espera mais frio do que p10, um em cada dez mais quente do que p90. Um spread de 0,4 °C é uma situação assente em que pode confiar; 3 °C quer dizer que os modelos discordam e que deve dizê-lo aos seus utilizadores em vez de escolher um.

Os limiares de chuva são decisões e não números redondos — 0,1 mm é molha de todo, 1 mm é leve casaco, 5 e 10 mm são isto é um problema. precipitation_p90 é o mau cenário: só um membro em cada dez é mais chuvoso.

Qualidade do ar#

Este é o endpoint que mais importa no Norte de África e no Mediterrâneo. Um episódio de poeiras leva as PM10 acima de mil microgramas por metro cúbico durante dias seguidos, o que é uma decisão de saúde e não um número, e está mal coberto pelos serviços gratuitos de consumo.

{
  "current": {
    "pm2_5": 38.7,
    "band": "poor",
    "who_guidelines_ug_m3": {"pm2_5": 15.0, "pm10": 45.0,
                             "nitrogen_dioxide": 25.0, "ozone": 100.0}
  },
  "hourly": {
    "time": ["2026-08-01T00:00:00+00:00"],
    "pm2_5": [38.7], "pm10": [85.8], "ozone": [43.4],
    "nitrogen_dioxide": [19.0], "dust_aod_550nm": [0.24]
  },
  "units": {"pm2_5": "ug/m3", "pm10": "ug/m3", "dust_aod_550nm": "1"}
}

Todas as concentrações estão em µg/m³, a unidade em que a qualidade do ar é citada em todo o lado. dust_aod_550nm é uma espessura ótica e não tem unidade: acima de cerca de 0,5 o céu está visivelmente enevoado, acima de 1,0 o sol fica apagado.

Os valores-guia de curto prazo da OMS viajam em cada resposta para que um número possa ser situado sem ir procurar. band segue o índice europeu de qualidade do ar para as PM2,5: bom, razoável, moderado, mau, muito mau, extremamente mau.

Neve e cota de neve#

Quatro campos, e respondem a perguntas diferentes. snowfall é quanta cai; os restantes descrevem o que está no chão e onde.

Peça-os pelo nome — não estão na resposta por omissão:

GET /v1/forecast?lat=45.19&lon=5.72&hourly=snowfall,snow_depth,snow_water_equivalent,snow_line_altitude,freezing_level_altitude

A cota de neve é a que vale a pena ler. «Chove aos 800 m e neva aos 1200» é uma decisão sobre a qual uma estação de esqui, uma autoridade rodoviária ou um condutor podem agir; «3 mm de precipitação» não é. Também importa no Norte de África — o Atlas tem áreas de esqui em Chréa e Tikjda, e os planaltos de Sétif, Batna e Djelfa ficam acima dos 1000 m.

Estes vêm do ICON do DWD, que cobre o mundo a 13 km. Os dados abertos do ECMWF publicam a espessura de neve mas não a cota de neve, pelo que este é um dos casos em que o modelo mais grosseiro é o mais útil. snow_line_altitude é um produto regional: o ICON-EU e o ICON-D2 publicam-no, o ICON global não, por isso fora da Europa recebe o nível de congelação e a espessura, mas não a cota.

Mar — estado do mar#

{
  "hourly": {
    "time": ["2026-08-01T00:00:00+00:00"],
    "wave_height": [0.32],
    "wave_direction": [264.3],
    "wave_period": [3.79],
    "wave_peak_period": [4.21]
  }
}

A altura das ondas é a altura significativa — a média do terço mais alto das ondas, que é aproximadamente o que um observador no mar reporta. As ondas individuais chegam ao dobro disso, e é esse o número que importa se está a decidir se sai. A direção é de onde as ondas vêm, como a direção do vento.

Rios#

Responde ao que nenhum modelo meteorológico consegue: não quanta chuva cai a montante, mas quanta água chega aqui — um número diferente, separado da chuva por uma bacia, por um estado de humidade do solo e por um dia ou dois de percurso.

{
  "disclaimer": "Information only. Only national and regional authorities
                 are authorised to issue flood warnings.",
  "daily": {
    "time": ["2026-08-01T00:00:00+00:00"],
    "river_discharge": [4.953],
    "soil_wetness_index": [0.448]
  }
}