PHPackages                             tuxonice/ipma-api - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. tuxonice/ipma-api

ActiveLibrary[API Development](/categories/api)

tuxonice/ipma-api
=================

PHP Package to manage IPMA API (https://api.ipma.pt/)

v0.6.1(2mo ago)1126MITPHPPHP ^8.1CI passing

Since Dec 27Pushed 1mo ago1 watchersCompare

[ Source](https://github.com/tuxonice/ipma-api)[ Packagist](https://packagist.org/packages/tuxonice/ipma-api)[ Docs](https://github.com/tuxonice/ipma-api)[ RSS](/packages/tuxonice-ipma-api/feed)WikiDiscussions main Synced today

READMEChangelog (8)Dependencies (19)Versions (14)Used By (0)

IPMA-API
========

[](#ipma-api)

[![Latest Version on Packagist](https://camo.githubusercontent.com/45242a15e2d42162db39ff9a4125cd49a438b69fbd620358c5ed2ef2c3c2ac9c/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7475786f6e6963652f69706d612d6170692e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/tuxonice/ipma-api)[![GitHub Tests Action Status](https://github.com/tuxonice/ipma-api/actions/workflows/pipeline.yml/badge.svg?branch=main)](https://github.com/tuxonice/ipma-api/actions)[![PHPStan Level](https://camo.githubusercontent.com/fff00cebb924e124a7335e6bd8ca8f8cf38869463c1654eff45d0939f1f21c57/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048505374616e2d6c6576656c253230382d627269676874677265656e2e7376673f7374796c653d666c61742d737175617265)](phpstan.neon)[![Total Downloads](https://camo.githubusercontent.com/1ba6fdabf602d4ed820bbdd0036e1e7e1395e9f45ddca94ca0ffb773dd9c0bf6/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f7475786f6e6963652f69706d612d6170692e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/tuxonice/ipma-api)[![License](https://camo.githubusercontent.com/250ff5b393fe93eb00b62faec76aea8d8e6765418216cd345916a012bb3feec0/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f7475786f6e6963652f69706d612d6170692e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/tuxonice/ipma-api)

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

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

Getting Started
---------------

[](#getting-started)

### Prerequisites

[](#prerequisites)

- PHP 8.1 or higher
- Composer

### Installation

[](#installation)

`composer require tuxonice/ipma-api`

---

Usage
-----

[](#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)](#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

[](#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

[](#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)

[](#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)
--------------------------

[](#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.`.

### Migrating from previous versions

[](#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
--------------

[](#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
-------------

[](#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
------------

[](#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
------------

[](#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](https://api.ipma.pt/):

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

###  Health Score

40

—

FairBetter than 86% of packages

Maintenance89

Actively maintained with recent releases

Popularity15

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity41

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~18 days

Recently: every ~3 days

Total

8

Last Release

63d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/916066?v=4)[Helder Correia](/maintainers/tuxonice)[@tuxonice](https://github.com/tuxonice)

---

Top Contributors

[![tuxonice](https://avatars.githubusercontent.com/u/916066?v=4)](https://github.com/tuxonice "tuxonice (34 commits)")

---

Tags

api-clientforecastipmaportugalweatherapi clientweatherforecastportugalipma

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP\_CodeSniffer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/tuxonice-ipma-api/health.svg)

```
[![Health](https://phpackages.com/badges/tuxonice-ipma-api/health.svg)](https://phpackages.com/packages/tuxonice-ipma-api)
```

###  Alternatives

[algolia/algoliasearch-client-php

API powering the features of Algolia.

69735.1M159](/packages/algolia-algoliasearch-client-php)[shopware/platform

The Shopware e-commerce core

3.4k1.5M3](/packages/shopware-platform)[kimai/kimai

Kimai - Time Tracking

4.8k9.0k1](/packages/kimai-kimai)[civicrm/civicrm-core

Open source constituent relationship management for non-profits, NGOs and advocacy organizations.

751291.4k43](/packages/civicrm-civicrm-core)[shopware/core

Shopware platform is the core for all Shopware ecommerce products.

585.6M574](/packages/shopware-core)[n1ebieski/ksef-php-client

PHP API client that allows you to interact with the API Krajowego Systemu e-Faktur

9067.8k](/packages/n1ebieski-ksef-php-client)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)