tempi-marathon/open-meteo-php

Saloon SDK for the Open-Meteo APIs

v1.0.0 2026-07-11 09:35 UTC

Requires

• php: ^8.5
• php-standard-library/php-standard-library: ^6.2
• saloonphp/saloon: ^4.0

Requires (Dev)

• illuminate/support: ^12.0|^13.0
• infection/infection: ^0.31 || ^0.34
• laravel/framework: ^13.0
• laravel/pint: ^1.27
• pestphp/pest: ^4.0
• pestphp/pest-plugin-mutate: ^4.0
• php-standard-library/phpstan-extension: ^2.1
• phpstan/phpstan: ^2.0
• phpstan/phpstan-strict-rules: ^2.0
• phpunit/phpunit: ^12.0

Suggests

• illuminate/support: Required for Laravel integration (^12.0|^13.0)

MIT

Published on Packagist.org on 2026-07-11 09:37 UTC

README

Framework-agnostic Saloon SDK for the Open-Meteo APIs.

Open-Meteo · Open-Meteo GitHub

No API key required. The free, non-commercial Open-Meteo API works out of the box — install the package and start making requests.

Requires PHP ^8.5.

Installation

composer require tempi-marathon/open-meteo-php

Quick start

use TempiMarathon\OpenMeteo\Enums\HourlyVariable;
use TempiMarathon\OpenMeteo\OpenMeteo;

$forecast = (new OpenMeteo())
    ->forecast()->weather()->get(52.52, 13.41)
    ->hourly(HourlyVariable::Temperature2m)
    ->dto();

No environment variables, configuration files, or Laravel setup needed.

Usage

Chain request options on the fluent builder, then call ->dto() for a typed response or ->send() for the raw Saloon response.

Facade (recommended entry point)

use TempiMarathon\OpenMeteo\Enums\HourlyVariable;
use TempiMarathon\OpenMeteo\Enums\Timezone;
use TempiMarathon\OpenMeteo\OpenMeteo;

$openMeteo = new OpenMeteo();

$locations = $openMeteo->geocoding()->locations()->search('Berlin')->dto();

$forecast = $openMeteo->forecast()->weather()->get(52.52, 13.41)
    ->timezone(Timezone::EuropeAmsterdam)
    ->hourly(HourlyVariable::Temperature2m, HourlyVariable::WeatherCode)
    ->forecastDays(7)
    ->dto();

Connectors (direct Saloon access)

use TempiMarathon\OpenMeteo\Connectors\ForecastConnector;
use TempiMarathon\OpenMeteo\Connectors\GeocodingConnector;
use TempiMarathon\OpenMeteo\Enums\Geocoding\GeocodingLanguage;
use TempiMarathon\OpenMeteo\Enums\HourlyVariable;
use TempiMarathon\OpenMeteo\Enums\Timezone;

$geocoding = new GeocodingConnector();

$locations = $geocoding->locations()->search('Berlin')
    ->count(5)
    ->language(GeocodingLanguage::English)
    ->dto();

$forecast = new ForecastConnector();

$data = $forecast->weather()->get(52.52, 13.41)
    ->timezone(Timezone::EuropeAmsterdam)
    ->hourly(HourlyVariable::Temperature2m, HourlyVariable::WeatherCode)
    ->forecastDays(7)
    ->dto();

Use debugUrl() on a resource to inspect the request URL during development. It redacts secrets such as API keys — see SECURITY.md.

Supported APIs

Facade method	API	Open-Meteo docs
forecast()	Weather forecast	Forecast API
historical()	Historical weather archive	Historical Weather API
geocoding()	Location search	Geocoding API
airQuality()	Air quality	Air Quality API
marine()	Marine weather	Marine Weather API
climate()	Climate	Climate API
flood()	Flood	Flood API
ensemble()	Ensemble forecast	Ensemble API
seasonal()	Seasonal forecast	Seasonal Forecast API
elevation()	Elevation	Elevation API

Optional configuration

User-Agent

Optional, but recommended in production so Open-Meteo can identify your application:

export OPENMETEO_USER_AGENT=my-app/1.0

Sent as the User-Agent header on every request.

Commercial subscriptions

Open-Meteo API keys are only for paid commercial subscriptions. The free API does not require a key.

When OPENMETEO_API_KEY is set, the SDK automatically:

1. Appends the key as an apikey query parameter on every request
2. Rewrites default free-tier *.open-meteo.com hosts to customer-*.open-meteo.com

# .env (Laravel) — all you need for commercial use
OPENMETEO_API_KEY=your-subscription-key
OPENMETEO_USER_AGENT=my-app/1.0

No manual host remapping required.

Non-Laravel apps can set the OPENMETEO_API_KEY environment variable (read by the package config) or bootstrap with:

use TempiMarathon\OpenMeteo\Support\OpenMeteoConfig;

OpenMeteoConfig::configure(['apikey' => 'your-subscription-key']);

Not every commercial plan includes every API — see the pricing table. Standard covers forecast, marine, air quality, geocoding, elevation, and flood; Professional adds historical, climate, ensemble, seasonal, and more.

Advanced: explicit host overrides

Explicit hosts in config always take precedence over auto-switching. Use this for self-hosted instances, debugging, or when you need a specific endpoint.

Config key	Free (default)	Commercial (auto or manual)
forecast	https://api.open-meteo.com/v1/	https://customer-api.open-meteo.com/v1/
historical	https://archive-api.open-meteo.com/v1/	https://customer-archive-api.open-meteo.com/v1/
geocoding	https://geocoding-api.open-meteo.com/v1/	https://customer-geocoding-api.open-meteo.com/v1/
air_quality	https://air-quality-api.open-meteo.com/v1/	https://customer-air-quality-api.open-meteo.com/v1/
marine	https://marine-api.open-meteo.com/v1/	https://customer-marine-api.open-meteo.com/v1/
climate	https://climate-api.open-meteo.com/v1/	https://customer-climate-api.open-meteo.com/v1/
flood	https://flood-api.open-meteo.com/v1/	https://customer-flood-api.open-meteo.com/v1/
ensemble	https://ensemble-api.open-meteo.com/v1/	https://customer-ensemble-api.open-meteo.com/v1/
seasonal	https://seasonal-api.open-meteo.com/v1/	https://customer-seasonal-api.open-meteo.com/v1/
elevation	https://api.open-meteo.com/v1/	https://customer-api.open-meteo.com/v1/

Self-hosted deployments should set custom hosts and leave apikey unset.

Laravel

The package auto-registers via Laravel package discovery. On first boot, config/openmeteo.php is copied to your application if it does not already exist.

All environment variables are optional:

# OPENMETEO_API_KEY=your-subscription-key
# OPENMETEO_USER_AGENT=my-app/1.0

Attribution

Open-Meteo data is licensed under CC BY 4.0. Geocoding data includes information from GeoNames — see ATTRIBUTIONS.md.

For commercial use boundaries and licensing, see Open-Meteo pricing.

Security

See SECURITY.md for API key handling and debugUrl() guidance.

Quality

Run composer test for Pint, PHPStan (max), and Pest (100% coverage).

Run composer test:infection for mutation testing (Pest mutate).

Contributing

See CONTRIBUTING.md for development setup and enum regeneration (composer generate).