README

This PHP package provides an easy-to-use interface for the IPMA (Instituto Português do Mar e da Atmosfera, I. P.) API. It allows you to fetch weather forecasts, observation data, and other auxiliary information directly into your PHP application.

For more information about the official API, please visit https://api.ipma.pt/ (only in Portuguese).

Important

This package is unofficial and IS NOT affiliated with, endorsed by, or maintained by Instituto Português do Mar e da Atmosfera, I. P. (IPMA, I.P.) It only provides a PHP client for the public API available at https://api.ipma.pt/.

Warning: This is a work in progress package! While it is actively maintained, some features may be incomplete or subject to change.

Getting Started

Prerequisites

• PHP 8.1 or higher
• Composer

Installation

composer require tuxonice/ipma-api

Usage

Heads up — breaking change: every factory now requires a PSR-16 Psr\SimpleCache\CacheInterface. This is intentional: IPMA asks consumers not to hammer their endpoints, and most of them change infrequently (locations, stations, forecasts). See Caching responses (PSR-16) below for setup.

Here are a few examples of how to use this package. All snippets assume $cache is a Psr\SimpleCache\CacheInterface instance (e.g. a Symfony\Component\Cache\Psr16Cache backed by any PSR-6 adapter).

Get Daily Weather Forecast

use Tlab\IpmaApi\IpmaForecast;

$api = IpmaForecast::createDailyWeatherForecastByLocalApi($cache);
$result = $api->from(1020500) // Location ID for Beja
              ->filterByMaxTemperatureRange(18.0, 19.0)
              ->get();

Get Seismic Information

use Tlab\IpmaApi\IpmaObservation;
use Tlab\IpmaApi\Enums\SeismicInformationAreaEnum;

$api = IpmaObservation::createSeismicInformationApi($cache);
$events = $api->from(SeismicInformationAreaEnum::MAIN_LAND_AND_MADEIRA)
              ->get();

Get Weather Stations (Service)

use Tlab\IpmaApi\IpmaService;

$api = IpmaService::createWeatherStationsApi($cache);
$stations = $api->filterByName('Lisboa', strict: false)->get();

All endpoints now return typed DTOs under Tlab\IpmaApi\Dto\*:

use Tlab\IpmaApi\Enums\SeismicInformationAreaEnum;
use Tlab\IpmaApi\IpmaObservation;

$events = IpmaObservation::createSeismicInformationApi($cache)
    ->from(SeismicInformationAreaEnum::MAIN_LAND_AND_MADEIRA)
    ->filterByMagnitude(2.0, 5.0)
    ->get();

foreach ($events as $event) {
    echo $event->regionName, ' -> ', $event->magnitude, "\n"; // typed access
}

// Call ->toArray() on any DTO to recover the old array shape.
$legacy = $events[0]->toArray();

For more detailed examples and a full list of available endpoints, please see the documentation folder.

Caching responses (PSR-16)

IPMA asks consumers to avoid hitting their endpoints too often. To enforce this, a PSR-16 Psr\SimpleCache\CacheInterface is required by every factory and by ApiConnector itself — there is no unbounded-request mode.

Any PSR-16 implementation works. Using symfony/cache as an example:

use Symfony\Component\Cache\Adapter\FilesystemAdapter;
use Symfony\Component\Cache\Psr16Cache;
use Tlab\IpmaApi\IpmaService;

$cache = new Psr16Cache(new FilesystemAdapter());

// Share the same $cache instance across every factory call:
$locations = IpmaService::createDistrictsIslandsLocationsApi($cache);
$stations  = IpmaService::createWeatherStationsApi($cache, ttlSeconds: 86400);

Every factory accepts an optional int $ttlSeconds = 3600 as its second argument. You can also construct the connector directly:

use Tlab\IpmaApi\ApiConnector;

$connector = new ApiConnector($cache, ttlSeconds: 3600);

Both JSON (fetchData) and CSV (fetchCsv) responses are cached. The raw CSV string is stored in cache and reconstructed as a Reader on hit. Cache keys are namespaced as ipma_api.<sha256(url)>.

Migrating from previous versions

• Tlab\IpmaApi\CachedApiConnector has been removed. Its caching behaviour is now built into ApiConnector.
• new ApiConnector() (no arguments) no longer works: you must pass a CacheInterface.
• IpmaForecast::create*Api(), IpmaObservation::create*Api() and IpmaService::create*Api() no longer accept an ApiConnectorInterface; they take (CacheInterface $cache, int $ttlSeconds = 3600) instead.
• The shared lazy default ApiConnector singleton inside the facades has been removed. Instantiate and share your own $cache (and therefore your own connectors) at the composition root.

Error handling

All errors raised by the library extend Tlab\IpmaApi\Exception\IpmaApiException:

• IpmaTransportException — network/TLS/timeout failures.
• IpmaResponseException — unexpected 3xx/4xx/5xx HTTP status.
• IpmaDecodingException — malformed JSON in the response body.

use Tlab\IpmaApi\Exception\IpmaApiException;
use Tlab\IpmaApi\IpmaForecast;

try {
    $data = IpmaForecast::createDailyWeatherForecastByLocalApi($cache)->from(1020500)->get();
} catch (IpmaApiException $e) {
    // $e->getPrevious() returns the underlying Symfony exception, if any.
    error_log($e->getMessage());
}

Running Tests

This project uses PHPUnit for testing. To run the test suite, you can use the provided Makefile command:

make test

To generate a code coverage report, run:

make coverage

The report will be generated in the coverage/ directory.

Contributing

Contributions are welcome! If you would like to contribute to this project, please follow these steps:

1. Fork the repository.
2. Create a new branch for your feature or bug fix.
3. Make your changes and commit them with a descriptive message.
4. Push your changes to your fork.
5. Submit a pull request to the main repository.

Please ensure that your code follows the existing coding style and that all tests pass before submitting a pull request.

Legal Notice

This package accesses data from the Instituto Português do Mar e da Atmosfera, I.P. (IPMA). When using this data, you must comply with IPMA's Terms and Conditions:

• Attribution required: Always reference IPMA as the source of information
• Non-commercial use: Data is free for personal or public use, but not for profit-making purposes
• When displaying IPMA information in web pages or hyperdocuments, IPMA states that the IPMA logo-symbol should be used and linked/referenced to the IPMA website.
• No warranty: IPMA provides data "as is" without guarantees of accuracy or availability

IPMA asks API users to read the usage conditions and to send an email to webmaster@ipma.pt informing them of the use and purpose of the service, for statistics and service improvement purposes.

The IPMA reserves the right to change or discontinue the API service at any time without notice.