README

This PHP package is an interface for IPMA(Instituto Português do Mar e da Atmosfera, I. P.) API.

For more information check https://api.ipma.pt/ (only in Portuguese)

Warning: This is a work in progress package!

Installation

composer require tuxonice/ipma-api

API

1. Forecast

🌤️ 1.1 Meteorology

1.1.1 Daily weather forecast up to 5 days aggregated by location

(Previsão meteorológica diária até 5 dias agregada por local)

https://api.ipma.pt/open-data/forecast/meteorology/cities/daily/{globalIdLocal}.json

use Tlab\IpmaApi\IpmaForecast;

$api = IpmaForecast::createDailyWeatherForecastByDayApi();
$result = $api->from(1020500)
              ->filterByMaxTemperatureRange(18.0, 19.0)
              ->get();

[
        [
            'forecastDate' => '2023-12-09',
            'idWeatherType' => 3,
            'windSpeedClass' => 1,
            'rainfallIntensity' => null,
            'rainfallProb' => 4.0,
            'minTemp' => 10.2,
            'maxTemp' => 18.2,
            'winDir' => 'W',
            'latitude' => 38.02,
            'longitude' => -7.87,
        ],
        [
            'forecastDate' => '2023-12-10',
            'idWeatherType' => 3,
            'windSpeedClass' => 1,
            'rainfallIntensity' => null,
            'rainfallProb' => 7.0,
            'minTemp' => 10.8,
            'maxTemp' => 18.3,
            'winDir' => 'SE',
            'latitude' => 38.02,
            'longitude' => -7.87,
        ],
],

1.1.2 Daily weather forecast for up to 3 days, aggregated information per day

(Previsão meteorológica diária até 3 dias, informação agregada por dia)

https://api.ipma.pt/open-data/forecast/meteorology/cities/daily/hp-daily-forecast-day{idDay}.json

use Tlab\IpmaApi\Enums\ForecastDayEnum;
use Tlab\IpmaApi\IpmaForecast;

$api = IpmaForecast::createDailyWeatherForecastByDayApi();
$result = $api
            ->from(ForecastDayEnum::TODAY)
            ->filterByIdWeatherType(3)
            ->get();

[
                [
                    'globalIdLocal' => 1020500,
                    'idWeatherType' => 3,
                    'windSpeedClass' => 1,
                    'rainfallIntensity' => null,
                    'rainfallProb' => 1.0,
                    'minTemp' => 11.0,
                    'maxTemp' => 18.0,
                    'winDir' => 'W',
                    'latitude' => 38.0200,
                    'longitude' => -7.8700,
                ],
                [
                    'globalIdLocal' => 1080500,
                    'idWeatherType' => 3,
                    'windSpeedClass' => 1,
                    'rainfallIntensity' => null,
                    'rainfallProb' => 0.0,
                    'minTemp' => 12.0,
                    'maxTemp' => 20.0,
                    'winDir' => 'SW',
                    'latitude' => 37.0146,
                    'longitude' => -7.9331,
                ],
                [
                    'globalIdLocal' => 1151300,
                    'idWeatherType' => 3,
                    'windSpeedClass' => 2,
                    'rainfallIntensity' => null,
                    'rainfallProb' => 27.0,
                    'minTemp' => 14.0,
                    'maxTemp' => 19.0,
                    'winDir' => 'SW',
                    'latitude' => 37.9560,
                    'longitude' => -8.8643,
                ],
            ]

1.1.3 Fire risk forecast for up to 2 days, aggregated information per day

(Previsão do risco de incêndio até 2 dias, informação agregada por dia)

https://api.ipma.pt/open-data/forecast/meteorology/rcm/rcm-d{idDay}.json

Fire risk code

1 - Low risk 2 - Moderate risk 3 - High risk 4 - Very high risk 5 - Maximum risk

use Tlab\IpmaApi\Enums\ForecastFireRiskDayEnum;
use Tlab\IpmaApi\Forecast\Meteorology\FireRiskForecast;

$api = IpmaForecast::createFireRiskForecastApi();
$result = $api
            ->from(ForecastFireRiskDayEnum::TODAY)
            ->filterByDico('1002')
            ->get()

   [
        [
            'dico' => '1002',
            'fireRiskLevel' => 1,
            'latitude' => 39.8222,
            'longitude' => -8.3814,
        ],
    ],

1.1.4 Ultraviolet risk forecast for up to 3 days (Ultraviolet Index)

(Previsão do risco de ultravioletas até 3 dias (Índice Ultravioleta)

https://api.ipma.pt/open-data/forecast/meteorology/uv/uv.json

use Tlab\IpmaApi\IpmaForecast;

$api = IpmaForecast::createUltravioletRiskForecastApi();
$result = $api->filterByUvIndex(2.4, 2.4)
              ->get();

[
        [
            'globalIdLocal' => 2320100,
            'forecastDate' => '2023-12-14',
            'uvIndex' => 2.4,
            'timeInterval' => '',
            'periodId' => 10,
        ],
],

🌊 1.2 Oceanography

1.2.1 Sea state forecast for up to 3 days, aggregated information per day

(Previsão do estado do mar até 3 dias, informação agregada por dia))

https://api.ipma.pt/open-data/forecast/oceanography/daily/hp-daily-sea-forecast-day{idDay}.json

Note: Only daily data is available. {idDay} ranges from 0 to 2, where:

• 0 - is the day equivalent to today
• 1 - tomorrow
• 2 - the day after tomorrow

use Tlab\IpmaApi\Enums\SeaStateForecastDayEnum;
use Tlab\IpmaApi\IpmaForecast;

$api = IpmaForecast::createSeaStateForecastApi();
$result = $api->from(SeaStateForecastDayEnum::TODAY)
              ->filterByGlobalIdLocal(2320126)
              ->filterByWavePeriodMax(5.0,6.0)
              ->get();

[
       [
            'wavePeriodMin' => '5.5',
            'globalIdLocal' => 2320126,
            'totalSeaMax' => 2.5,
            'waveHighMax' => '2.2',
            'waveHighMin' => '1.6',
            'longitude' => '-16.3400',
            'wavePeriodMax' => '5.7',
            'latitude' => '33.2500',
            'totalSeaMin' => 2.0,
            'sstMax' => '21.8',
            'predWaveDir' => 'NE',
            'sstMin' => '21.7',
       ],
],

🌀 1.3 Warnings

1.3.1 Weather warnings for up to 3 days

(Avisos meteorológicos até 3 dias)

https://api.ipma.pt/open-data/forecast/warnings/warnings_www.json

use Tlab\IpmaApi\IpmaService;

$warningsApi = IpmaService::createWarningsApi();
$result = $warningsApi->query()
    ->filterByWarningIdArea('BGC')
    ->filterByAwarenessTypeName('Nevoeiro')
    ->get();

[
  [
    "text": "",
    "awarenessTypeName": "Agitação Marítima",
    "warningIdArea": "BGC",
    "startTime": "2021-03-25T07:25:00",
    "awarenessLevelID": "green",
    "endTime": "2021-03-28T07:00:00"
  ],
  [
    "text": "",
    "awarenessTypeName": "Nevoeiro",
    "warningIdArea": "BGC",
    "startTime": "2021-03-25T07:25:00",
    "awarenessLevelID": "green",
    "endTime": "2021-03-28T07:00:00"
  ]
]

2. Observation

🌐 2.1 Seismic

Seismic information, Arch. Azores, Main land and Arch. Madeira. Includes 30 days of information

(Informação sismicidade, Arq. Açores, Continente e Arq. Madeira. Integra 30 dias de informação)

https://api.ipma.pt/open-data/observation/seismic/{idArea}.json

Available Areas:

• SeismicInformationAreaEnum::AZORES (3) - Azores Archipelago
• SeismicInformationAreaEnum::MAIN_LAND_AND_MADEIRA (7) - Mainland Portugal and Madeira

Response Fields:

Available Methods:

• from(SeismicInformationAreaEnum $area) - Fetch seismic data for a specific area
• filterByDepth(int $minValue, int $maxValue) - Filter by depth range
• filterByMagnitude(float $minValue, float $maxValue) - Filter by magnitude range
• filterByTime(string $from, string $to) - Filter by time range
• findLocationsByDistance(float $latitude, float $longitude, float $radio) - Find events within distance (km)
• findLocationByNearDistance(float $latitude, float $longitude) - Find nearest event to coordinates
• getLastSeismicActivityDate() - Get last seismic activity date
• getUpdateDate() - Get data update date
• get() - Get filtered results

Example Usage:

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

$api = IpmaService::createSeismicInformationApi();

// Get all seismic events for mainland and Madeira
$events = $api->from(SeismicInformationAreaEnum::MAIN_LAND_AND_MADEIRA)
              ->get();

// Filter by magnitude range
$strongEvents = $api->from(SeismicInformationAreaEnum::MAIN_LAND_AND_MADEIRA)
                    ->filterByMagnitude(3.0, 5.0)
                    ->get();

// Filter by depth range
$shallowEvents = $api->from(SeismicInformationAreaEnum::MAIN_LAND_AND_MADEIRA)
                     ->filterByDepth(0, 30)
                     ->get();

// Find events near specific coordinates (within 50km radius)
$nearbyEvents = $api->from(SeismicInformationAreaEnum::MAIN_LAND_AND_MADEIRA)
                    ->findLocationsByDistance(38.7223, -9.1393, 50)
                    ->get();

// Find the nearest event to specific coordinates
$nearestEvent = $api->from(SeismicInformationAreaEnum::MAIN_LAND_AND_MADEIRA)
                    ->findLocationByNearDistance(38.7223, -9.1393);

// Filter by time range
$recentEvents = $api->from(SeismicInformationAreaEnum::MAIN_LAND_AND_MADEIRA)
                    ->filterByTime('2024-01-01T00:00:00', '2024-01-31T23:59:59')
                    ->get();

// Combine multiple filters
$filteredEvents = $api->from(SeismicInformationAreaEnum::AZORES)
                      ->filterByMagnitude(2.0, 4.0)
                      ->filterByDepth(10, 50)
                      ->get();

// Get metadata
$lastActivity = $api->from(SeismicInformationAreaEnum::MAIN_LAND_AND_MADEIRA)
                    ->getLastSeismicActivityDate();
$updateDate = $api->getUpdateDate();

Example Response:

[
    [
        'seismId' => '20240117095931C',
        'googleMapRef' => 'http://maps.google.com/maps?output=classic&q=38.0990+-8.2530...',
        'degree' => null,
        'magType' => 'L',
        'magnitude' => 3.0,
        'depth' => 7,
        'tensorRef' => '',
        'shakeMapId' => '2024011709593101',
        'shakeMapRef' => 'http://shakemap.ipma.pt/2024011709593101/intensity.html',
        'location' => null,
        'regionName' => 'NW Ferreira do Alentejo',
        'latitude' => 38.0990,
        'longitude' => -8.2530,
        'source' => 'IPMA',
        'sensed' => null,
        'time' => '2024-01-17T09:59:32',
        'updateDate' => '2024-01-23T18:00:00',
    ],
]

🐠 2.2 Biology

2.2.1 Prohibitions on harvesting in bivalve mollusc production areas (GeoJSON format)

(Interdições à apanha nas zonas de produção de moluscos bivalves (formato GeoJSON))

https://api.ipma.pt/open-data/observation/biology/bivalves/CI_SNMB.geojson

Notes:

State of the Zone:

• "Open": Situation of Personal Permission and Capture,
• "Partial_open": Situation of Partial Permission of caught and capture,
• "closed": situation of total interdiction of caught and capture,
• "partial_open",
• "noinfo": without information

Interdictions

• "Specie_S": scientific name (scientific name);
• "Specie_c": Common Name (Common Name);
• "Classification": Sanitary Statute ("A", "B", "C")

use Tlab\IpmaApi\IpmaObservation;

$molluscHarvestingProhibition = IpmaObservation::createMolluscHarvestingProhibitionApi();
$result = $molluscHarvestingProhibition
    ->from()
    ->filterByName('tavira')
    ->get();

[
                    'type' => 'Feature',
                    'properties' => [
                        'name' => 'Litoral Tavira – Vila Real Santo António',
                        'code' => 'L9',
                        'zone_type' => 'LITORAL',
                        'region_name' => 'Algarve',
                        'representative_point' => 'POINT (-7.521726250000002 37.094826)',
                        'status' => 'OPEN',
                        'interdictions' => [
                            'open' => [
                                [
                                    'specie_c' => 'Canilha',
                                    'specie_s' => 'Bolinus brandaris',
                                    'classification' => 'NA',
                                ],
                                [
                                    'specie_c' => 'Pé-de-burrinho',
                                    'specie_s' => 'Chamelea gallina',
                                    'classification' => 'A*',
                                ],
                                [
                                    'specie_c' => 'Buzina',
                                    'specie_s' => 'Charonia rubicunda',
                                    'classification' => 'NA',
                                ],
                                [
                                    'specie_c' => 'Conquilha',
                                    'specie_s' => 'Donax trunculus',
                                    'classification' => 'B',
                                ],
                                [
                                    'specie_c' => 'Amêijoa-branca',
                                    'specie_s' => 'Spisula solida',
                                    'classification' => 'B',
                                ],
                            ],
                            'close' => [],
                        ],
                        'coords' => [
                            'latitude' => '37.094826',
                            'longitude' => '-7.521726250000002',
                        ],
                    ],
                ],
                [
                    'type' => 'Feature',
                    'properties' => [
                        'name' => 'Ria Formosa, Tavira',
                        'code' => 'TAV',
                        'zone_type' => 'EST_LAG',
                        'region_name' => 'Algarve',
                        'representative_point' => 'POINT (-7.673624507077854 37.08832)',
                        'status' => 'OPEN',
                        'interdictions' => [
                            'open' => [
                                [
                                    'specie_c' => 'Berbigão',
                                    'specie_s' => 'Cerastoderma edule',
                                    'classification' => 'C',
                                ],
                                [
                                    'specie_c' => 'Ostra-japonesa/gigante',
                                    'specie_s' => 'Magallana gigas',
                                    'classification' => 'B',
                                ],
                                [
                                    'specie_c' => 'Mexilhão',
                                    'specie_s' => 'Mytilus spp.',
                                    'classification' => 'B',
                                ],
                                [
                                    'specie_c' => 'Amêijoa-boa',
                                    'specie_s' => 'Ruditapes decussatus',
                                    'classification' => 'C',
                                ],
                                [
                                    'specie_c' => 'Longueirão',
                                    'specie_s' => 'Solen marginatus',
                                    'classification' => 'C',
                                ],
                            ],
                            'close' => [],
                        ],
                        'coords' => [
                            'latitude' => '37.08832',
                            'longitude' => '-7.673624507077854',
                        ],
                    ],
                ],

3. Auxiliary services

3.1 List of identifiers for district capitals and islands

$api = IpmaService::createDistrictsIslandsLocationsApi();
$result = $api->query()
              ->filterByIdRegion(1)
              ->filterByIdWarningArea('MCS')
              ->get();

[
    [
        'globalIdLocal' => 2310300,
        'name' => 'Funchal',
        'idMunicipality' => 3,
        'idDistrict' => 31,
        'idRegion' => 2,
        'idWarningArea' => 'MCS',
        'latitude' => 32.6485,
        'longitude' => -16.9084,
    ],
    [
        'globalIdLocal' => 2320100,
        'name' => 'Porto Santo',
        'idMunicipality' => 1,
        'idDistrict' => 32,
        'idRegion' => 2,
        'idWarningArea' => 'MPS',
        'latitude' => 33.0700,
        'longitude' => -16.3400,
    ],
],

3.2 List of identifiers for coastal regions

(Lista de identificadores para as regiões costeiras)

https://api.ipma.pt/open-data/sea-locations.json

$api = IpmaService::createSeaLocationsApi();
$result = $api->query()
              ->filterByIdRegiao(1)
              ->filterByIdAreaAviso('AVR')
              ->get();

[
  {
    "globalIdLocal": 1060526,
    "name": "Figueira da Foz, Costa",
    "idLocal": 302,
    "idRegion": 1,
    "idWarningArea": "CBR",
    "latitude": "40.1417",
    "longitude": "-8.8783"
  }
]

3.3 List of weather station identifiers

(Lista de identificadores das estações meteorológicas)

https://api.ipma.pt/open-data/observation/meteorology/stations/stations.json

$api = IpmaService::createWeatherStationsApi();
$result = $api->filterByName('selvagens')
              ->get();

[
    [
        'id' => 1210520,
        'name' => 'Ilhas selvagens',
        'latitude' => 30.140595,
        'longitude' => -15.869153,
    ]
]

3.4 List of Weather Type Identifiers

(Lista de identificadores do tempo significativo)

https://api.ipma.pt/open-data/weather-type-classe.json

3.5 List of classes relating to wind intensity

(Lista de classes relativa à intensidade vento)

https://api.ipma.pt/open-data/wind-speed-daily-classe.json

3.6 List of classes relating to precipitation intensity

(Lista de classes relativa à intensidade precipitação)

https://api.ipma.pt/open-data/precipitation-classe.json