weather_open_meteo_client 1.1.1
weather_open_meteo_client: ^1.1.1 copied to clipboard
A Dart client for every free Open-Meteo API — forecast, historical, air quality, marine, flood, climate, ensemble, seasonal, satellite and geocoding. No API key required.
weather_open_meteo_client #
A Dart client for every free Open-Meteo API. No API key required.
Pure Dart — works in Flutter apps, server-side Dart and CLI tools alike.
| API | Client | Returns |
|---|---|---|
| Forecast | OpenMeteoApi |
Current, hourly and daily weather |
| Geocoding | OpenMeteoApi |
Places matching a name |
| Historical | HistoricalApi |
Reanalysis back to 1940 |
| Air Quality | AirQualityApi |
Pollutants, pollen, AQI |
| Marine | MarineApi |
Waves, swell, currents |
| Flood | FloodApi |
River discharge |
| Climate | ClimateApi |
CMIP6 projections |
| Ensemble | EnsembleApi |
Per-member forecasts |
| Seasonal | SeasonalApi |
Months ahead, as an ensemble |
| Satellite Radiation | SatelliteRadiationApi |
Solar irradiance |
| Elevation | ElevationApi |
Terrain height |
Every client takes the same shape: pass the variables you want as enum values, read them back as typed fields of the same name.
Install #
dependencies:
weather_open_meteo_client: ^1.1.0
Usage #
By city name #
import 'package:weather_open_meteo_client/weather_open_meteo_client.dart';
final api = OpenMeteoApi();
final weather = await api.getWeatherByCityName('London');
print('${weather.current?.temperature2m}${weather.currentUnits?.temperature2m}');
api.close();
By coordinate #
Request exactly the variables you need — each one is an enum value, and the matching field on the response carries the same name:
final weather = await api.getWeatherByCoordinate(
latitude: 51.5072,
longitude: -0.1275,
current: [CurrentParam.temperature2m, CurrentParam.weatherCode],
hourly: [HourlyParam.temperature2m, HourlyParam.precipitationProbability],
daily: [DailyParam.temperature2mMax, DailyParam.sunrise, DailyParam.sunset],
forecastDays: 3,
);
print(weather.current?.temperature2m); // 25.9
print(weather.hourly?.temperature2m?.first); // 19.2
print(weather.daily?.sunrise?.first); // DateTime
Anything you did not request stays null, and every series is aligned with the
time series of the block it belongs to:
final hourly = weather.hourly!;
for (var i = 0; i < hourly.time.length; i++) {
print('${hourly.time[i]}: ${hourly.temperature2m?[i]}');
}
Units and options #
await api.getWeatherByCoordinate(
latitude: 51.5072,
longitude: -0.1275,
current: [CurrentParam.temperature2m],
temperatureUnit: TemperatureUnit.fahrenheit,
windSpeedUnit: WindSpeedUnit.mph,
precipitationUnit: PrecipitationUnit.inch,
timezone: Timezone.europeLondon, // any IANA name; defaults to Timezone.auto
pastDays: 2,
startDate: DateTime(2026, 1, 1), // or an explicit interval
endDate: DateTime(2026, 1, 7),
);
Timestamps always arrive as DateTime, whether the API was asked for ISO8601 or
TimeFormat.unixtime. Unix timestamps decode as UTC; ISO8601 ones decode as
local wall time in the requested timezone.
Geocoding #
final places = await api.searchLocations('Springfield', count: 5);
for (final place in places) {
print('${place.name}, ${place.admin1}, ${place.country} — ${place.population}');
}
final best = await api.findLocation('London'); // throws if nothing matches
Errors #
Every failure is an OpenMeteoException, carrying the reason reported by the
API and the request that failed:
try {
await api.getWeatherByCityName('nowhere at all');
} on LocationNotFoundFailure catch (e) {
print(e.message);
} on OpenMeteoException catch (e) {
print('${e.message} (${e.uri})');
}
| Exception | Thrown when |
|---|---|
WeatherRequestFailure |
A forecast request failed or was rejected |
WeatherResponseFailure |
A forecast response could not be parsed |
LocationRequestFailure |
A geocoding request failed or was rejected |
LocationNotFoundFailure |
No place matched the query |
Lifetime #
OpenMeteoApi creates an http.Client unless you pass one. Reuse a single
instance and close() it when done; a client you passed in is left for you to
close.
final api = OpenMeteoApi(httpClient: myClient); // shared, not closed by close()
The other APIs #
Each endpoint has its own client and its own variable enums, but they all work the way the forecast API does.
final air = await AirQualityApi().getAirQuality(
latitude: 52.52,
longitude: 13.41,
current: [AirQualityParam.europeanAqi, AirQualityParam.pm25],
);
print('${air.current?.europeanAqi} ${air.currentUnits?.pm25}');
final sea = await MarineApi().getMarine(
latitude: 54.54,
longitude: 8.0,
hourly: [MarineHourlyParam.waveHeight, MarineHourlyParam.swellWavePeriod],
);
final past = await HistoricalApi().getHistorical(
latitude: 52.52,
longitude: 13.41,
startDate: DateTime(2020, 1, 1),
endDate: DateTime(2020, 12, 31),
daily: [HistoricalDailyParam.temperature2mMax],
);
final metres = await ElevationApi().getElevation(
latitude: 27.98,
longitude: 86.92,
);
Ensembles #
Ensemble and seasonal forecasts return one series per member — 40-ish for a single ICON run, up to 51 for seasonal — and how many depends on the models requested. They are the one place typed fields cannot work, so their blocks are keyed by variable instead:
final runs = await EnsembleApi().getEnsemble(
latitude: 52.52,
longitude: 13.41,
models: [EnsembleModel.iconSeamlessEps],
hourly: [EnsembleParam.temperature2m],
);
final hourly = runs.hourly!;
hourly(EnsembleParam.temperature2m); // control run
hourly.member(EnsembleParam.temperature2m, 1); // first member
hourly.members(EnsembleParam.temperature2m); // all of them
hourly.memberCount(EnsembleParam.temperature2m); // 39
Examples #
Eight runnable examples live in example/ — air quality, marine,
historical, ensembles, geocoding, error handling and sharing an HTTP client.
Each needs no key and no setup:
dart run example/example.dart London
dart run example/ensemble_example.dart Berlin
dart run example/historical_example.dart Berlin 2023
See example/README.md for the full list.
API documentation #
Every client links to the endpoint it wraps in its own documentation. Start from the Open-Meteo docs for the meaning of individual variables.
License #
MIT — see LICENSE.