Why
Typed weather data, minus the quirks
IPMA's open data is free and rich, but its shapes are inconsistent — mixed envelopes, numbers-as-strings, and -99 sentinels. These SDKs give you typed models across every shape, in three languages.
Forecasts
5-day city forecasts and aggregated daily feeds by location.
Warnings & UV
Meteorological warnings and the UV-index forecast.
Fire risk & seismic
Rural fire-risk (RCM) by municipality and seismic observations.
Resilient
Auto-retries on 5xx with exponential backoff.
Install
Add it to your project
npm install ipma-api<dependency>
<groupId>io.github.marcelogdomingues</groupId>
<artifactId>ipma-api</artifactId>
<version>0.1.0</version>
</dependency>dotnet add package Ipma.ApiQuick start
Get a 5-day forecast
import { IpmaClient } from "ipma-api";
const ipma = new IpmaClient();
// Lisboa = 1110600 (find ids via ipma.locations())
const f = await ipma.cityForecast(1110600);
console.log(f.data[0]?.tMin, f.data[0]?.tMax);
await ipma.warnings(); // Warning[]
await ipma.fireRisk(0); // FireRiskResponseIpmaClient ipma = IpmaClient.builder().build();
Envelope<DailyForecast> f = ipma.cityForecast(1110600);
System.out.println(f.data.get(0).tMin + " / " + f.data.get(0).tMax);
List<Warning> warnings = ipma.warnings();
FireRiskResponse risk = ipma.fireRisk(0);var ipma = new IpmaClient();
var f = await ipma.CityForecastAsync(1110600);
Console.WriteLine($"{f.Data[0].TMin} / {f.Data[0].TMax}");
var warnings = await ipma.WarningsAsync();
var risk = await ipma.FireRiskAsync(0);Data shapes
How the feeds join together
IPMA feeds link through shared ids. Start from locations() to get a globalIdLocal and an idAreaAviso, then fan out.
flowchart TD
L["locations()
globalIdLocal · idAreaAviso"] --> F["cityForecast(globalIdLocal)"]
L --> U["uvIndex()
by globalIdLocal"]
L --> W["warnings()
by idAreaAviso"]
F --> T["weatherTypes()
idWeatherType → text"]
F --> WS["windSpeedClasses()
classWindSpeed → text"]
Heads-up: most endpoints wrap results in { owner, country, data[] }, but warnings and UV are bare arrays and fire-risk uses local[]. Numbers are often strings; -99 means missing.
Reference
API surface
Shown in TypeScript form; Java is the same in camelCase, C# adds Async.
| Area | Methods | Endpoint |
|---|---|---|
| Locations | locations | distrits-islands.json |
| Forecasts | cityForecast · dailyForecast | forecast/meteorology/cities/daily/… |
| Warnings | warnings | forecast/warnings/warnings_www.json |
| UV index | uvIndex | forecast/meteorology/uv/uv.json |
| Fire risk | fireRisk | forecast/meteorology/rcm/rcm-d{idDay}.json |
| Seismic | seismic | observation/seismic/{idArea}.json |
| Reference | weatherTypes · windSpeedClasses · precipitationClasses | classification tables |
FAQ
Common questions
Do I need an API key?
No — the IPMA open-data API is free and keyless. Please attribute "source: IPMA" and read the conditions of use.
How do I turn a weather-type id into text?
Fetch weatherTypes() once and map idWeatherType → descWeatherTypePT/EN. Same for wind-speed and precipitation classes.
Is this affiliated with IPMA?
No — it's an independent community client.