Unofficial, multi-language client SDKs for the IPMA open-data weather API (Portugal).
Forecasts, warnings, UV index, fire risk and seismic data — free API, no key required.
Important
This is an unofficial community project. It is not affiliated with, endorsed by, or supported by IPMA. Data is free to use with attribution ("source: IPMA") — please read IPMA's conditions of use.
The IPMA open-data API is a great free weather source, but its shapes are
inconsistent: most endpoints wrap results as { owner, country, data: [...] },
but warnings and UV are bare arrays, fire-risk uses local[], numbers often arrive
as strings, and -99 means "missing". These SDKs give you typed models across
all those shapes, join keys documented, and the same clean API in three languages.
- const r = await fetch("https://api.ipma.pt/open-data/forecast/.../1110600.json"); // parse odd shapes…+ const f = await ipma.cityForecast(1110600); // f.data[0].tMax| Language | Folder | Install | Runtime | Docs |
|---|---|---|---|---|
| 🟦 TypeScript / Node | typescript/ | npm install ipma-api | Node ≥ 18, zero deps | README |
| ☕ Java | java/ | io.github.marcelogdomingues:ipma-api | Java 17+ | README |
| 🟣 .NET / C# | dotnet/ | dotnet add package Ipma.Api | net8.0 | README |
All three expose the same API surface.
| TypeScript | Java | C# |
|---|---|---|
import{IpmaClient}from"ipma-api";constipma=newIpmaClient();constlisboa=1110600;constf=awaitipma.cityForecast(lisboa);console.log(f.data[0]?.tMin,f.data[0]?.tMax); | IpmaClientipma =
IpmaClient.builder().build();
varf = ipma.cityForecast(1110600);
System.out.println(f.data.get(0).tMax); | varipma=newIpmaClient();varf=awaitipma.CityForecastAsync(1110600);Console.WriteLine(f.Data[0].TMax); |
Find a location's globalIdLocal via locations().
Wraps the IPMA open-data API (https://api.ipma.pt/open-data):
| Area | Methods | Endpoint |
|---|---|---|
| Locations | locations() | distrits-islands.json |
| Forecasts | cityForecast(id), dailyForecast(idDay) | forecast/meteorology/cities/daily/… |
| Warnings | warnings() | forecast/warnings/warnings_www.json |
| UV index | uvIndex() | forecast/meteorology/uv/uv.json |
| Fire risk | fireRisk(idDay) | forecast/meteorology/rcm/rcm-d{idDay}.json |
| Seismic | seismic(idArea) | observation/seismic/{idArea}.json |
| Reference tables | weatherTypes(), windSpeedClasses(), precipitationClasses() | classification tables |
All clients retry automatically on 5xx with exponential backoff.
- Envelopes vary: most are
{ owner, country, data[] }; warnings and UV are bare arrays; fire-risk useslocal[]. - Numbers are often strings (
tMin,latitude,iUv). The SDKs keep them faithful;.NETalso accepts numerictMin/tMaxtransparently. - Sentinels:
-99/-99.0/nullmean "missing". - Join keys:
globalIdLocal(locations ↔ forecast ↔ UV),idAreaAviso(locations ↔ warnings),dico(fire-risk municipality),idWeatherType/classWindSpeed/classPrecInt(→ reference tables).
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 pattern for wind-speed and precipitation classes.
Is this affiliated with IPMA?
No — it's an independent community client.
- TypeScript, Java and .NET clients with parity
- Forecasts · warnings · UV · fire risk · seismic · reference tables
- Auto-retry on 5xx
- Publish to npm / Maven Central / NuGet
- Station observations & sea-state forecast helpers
- Weather-type description resolver helper
MIT © Marcelo Domingues · Data © IPMA (attribution required)