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).

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

Here are a few examples of how to use this package.

Get Daily Weather Forecast

use Tlab\IpmaApi\IpmaForecast;

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

Get Seismic Information

use Tlab\IpmaApi\IpmaService;
use Tlab\IpmaApi\Enums\SeismicInformationAreaEnum;

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

Get Weather Stations (Service)

use Tlab\IpmaApi\IpmaService;

$api = IpmaService::createWeatherStationsApi();
$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()
    ->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)

Most IPMA endpoints change infrequently (locations, stations, forecasts). The library ships with a PSR-16 caching decorator you can wrap around any ApiConnectorInterface:

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

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

// Pass the cached connector to any factory:
$api = IpmaService::createDistrictsIslandsLocationsApi($connector);

Only JSON responses (fetchData) are cached; CSV responses are passed through.

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::createDailyWeatherForecastByDayApi()->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:

Fork the repository.
Create a new branch for your feature or bug fix.
Make your changes and commit them with a descriptive message.
Push your changes to your fork.
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.

tuxonice / ipma-api

Maintainers

Package info

Statistics

Security