Unofficial, multi-language client SDKs for current air quality and coastal/marine conditions anywhere in Portugal.
European AQI, PM2.5/PM10, NO₂, O₃, UV — plus sea temperature and waves for the beach. Free, no API key.
Important
This is an unofficial community project. Data comes from the free Open-Meteo APIs (air quality from CAMS/Copernicus, marine from wave models). Values are modelled forecasts/analyses, not official station measurements — respect Open-Meteo's terms (CC-BY 4.0).
"Is the air OK today?" and "how cold is the sea at the beach?" are two questions
with great free data behind them — but the Open-Meteo response wraps everything in
a dynamic current object keyed by variable name, with mixed types and nulls.
These SDKs give you typed snapshots (AirQuality, MarineConditions), an
AQI band helper, and a handful of ready-made Portuguese coordinates — the
same clean API in three languages.
- const r = await (await fetch(".../air-quality?...¤t=european_aqi,pm2_5")).json(); const aqi = r.current.european_aqi; // dynamic keys, nulls…
+ const air = await env.airQuality(38.72, -9.14);
+ europeanAqiBand(air.europeanAqi); // "Fair"| Language | Folder | Install | Runtime | Docs |
|---|---|---|---|---|
| 🟦 TypeScript / Node | typescript/ |
npm install ambiente-pt |
Node ≥ 18, zero deps | README |
| ☕ Java | java/ |
io.github.marcelogdomingues:ambiente |
Java 17+ | README |
| 🟣 .NET / C# | dotnet/ |
dotnet add package Ambiente |
net8.0 | README |
All three expose the same API surface.
| TypeScript | Java | C# |
|---|---|---|
import { AmbienteClient, europeanAqiBand, PLACES } from "ambiente-pt";
const env = new AmbienteClient();
const air = await env.airQuality(PLACES.Lisboa.lat, PLACES.Lisboa.lon);
console.log(air.europeanAqi, europeanAqiBand(air.europeanAqi));
const sea = await env.marine(PLACES.CascaisBeach.lat, PLACES.CascaisBeach.lon);
console.log(sea.seaSurfaceTemperature, sea.waveHeight); |
AmbienteClient env = AmbienteClient.builder().build();
AirQuality air = env.airQuality(
Places.LISBOA.lat(), Places.LISBOA.lon());
System.out.println(air.europeanAqiBand());
MarineConditions sea = env.marine(
Places.CASCAIS_BEACH.lat(), Places.CASCAIS_BEACH.lon()); |
var env = new AmbienteClient();
var air = await env.AirQualityAsync(
Places.Lisboa.Lat, Places.Lisboa.Lon);
Console.WriteLine(air.Band());
var sea = await env.MarineAsync(
Places.CascaisBeach.Lat, Places.CascaisBeach.Lon); |
Wraps the free Open-Meteo APIs:
| Area | Method | Source |
|---|---|---|
| Air quality | airQuality(lat, lon) |
Open-Meteo Air-Quality (CAMS) |
| Coastal / marine | marine(lat, lon) |
Open-Meteo Marine (wave models) |
AirQuality carries europeanAqi, pm10, pm25, nitrogenDioxide, ozone,
sulphurDioxide, carbonMonoxide and uvIndex. MarineConditions carries
seaSurfaceTemperature, waveHeight, wavePeriod and waveDirection. Missing
values come back as null. PLACES / Places ships coordinates for major cities
and popular beaches.
The europeanAqiBand / EuropeanAqiBand helper maps the European AQI to its band:
| AQI | Band |
|---|---|
| 0–20 | Good |
| 20–40 | Fair |
| 40–60 | Moderate |
| 60–80 | Poor |
| 80–100 | Very poor |
| > 100 | Extremely poor |
Errors throw AmbienteError / AmbienteException.
Do I need an API key?
No — Open-Meteo is free for non-commercial use with no key. For heavy or commercial use, see Open-Meteo's terms and paid plans.
Are these official measurements?
No. Air quality comes from the CAMS model and marine from wave models — great for "is it good today?", but not a substitute for official station data (e.g. APA QualAr) when you need certified measurements.Can I use any coordinate?
Yes — pass any latitude/longitude.PLACES / Places is just a convenience set of Portuguese cities and beaches.
Is this affiliated with Open-Meteo?
No — it's an independent community client.- TypeScript, Java and .NET clients with parity
- Air quality (AQI, pollutants, UV) + marine (sea temp, waves)
- AQI band helper + Portuguese place presets · live-tested
- Publish to npm / Maven Central / NuGet
- Hourly forecast series and pollen counts
MIT © Marcelo Domingues · Data © Open-Meteo (CC-BY 4.0)