OpenWeatherMap PHP API

A fluent PHP client for OpenWeather APIs covering current and forecast weather, air pollution, geocoding, maps, stations, and One Call. Responses use typed entities that safely handle conditional, missing, and null data.

The library is built on programmatordev/php-api-sdk, which provides HTTP client discovery and optional caching, logging, plugins, and request hooks.

Requirements

• PHP 8.1 or higher
• An OpenWeather API key

Installation

Install the library with Composer:

composer require programmatordev/openweathermap-php-api

Getting Started

Create the API client with an OpenWeather API key, then choose an API and call one of its methods:

use ProgrammatorDev\OpenWeatherMap\OpenWeatherMap;

$api = new OpenWeatherMap($_ENV['OPENWEATHERMAP_API_KEY']);

$current = $api->weather()->current(
    latitude: 38.7223,
    longitude: -9.1393,
);

echo $current->temperature();
echo $current->temperatureWithUnit();

Response properties may be missing or null, so getters return nullable values where appropriate. Collection getters return empty arrays when the response does not contain that collection.

Configuration

The client defaults to metric units and English. The equivalent explicit configuration is:

use ProgrammatorDev\OpenWeatherMap\Enum\Language;
use ProgrammatorDev\OpenWeatherMap\Enum\Units;
use ProgrammatorDev\OpenWeatherMap\OpenWeatherMap;

$api = new OpenWeatherMap(
    apiKey: $_ENV['OPENWEATHERMAP_API_KEY'],
    options: [
        'units' => Units::METRIC,
        'language' => Language::ENGLISH,
    ],
);

Weather and One Call requests can override those values for one fluent request chain. The client-wide configuration remains unchanged for later requests:

$current = $api
    ->weather()
    ->withUnits(Units::IMPERIAL)
    ->withLanguage(Language::PORTUGUESE)
    ->current(latitude: 38.7223, longitude: -9.1393);

withLanguage() also accepts a non-empty language-code string, allowing new OpenWeather languages to be used without waiting for an enum update.

See OpenWeather's units of measurement and multilingual support documentation for the currently supported values.

Documentation

APIs

These guides cover each API's endpoints, response entities, and usage examples:

• One Call 4.0
• Air Pollution
• Weather
• Maps
• Stations
• Geocoding

Client Guides

These guides cover client configuration and failures shared across the APIs:

• Setup — Configure caching, logging, HTTP clients, plugins, and request hooks.
• Error Handling — Handle OpenWeather API errors and client failures.

Upgrading

Version 4 is a complete rewrite without backward compatibility. Existing integrations should treat it as a new implementation. See Upgrading To 4.0 for the release expectations and current baseline.

License

This project is licensed under the MIT License.