README

🇩🇰🤧 Pollen measurements from Astma-Allergi Denmark

Astma-Allergi Denmark does unfortunately not offer an official API for the latest pollen measurements in Denmark.

This package is (in some form) a workaround for that. It fetches the latest measurements and short-term predictions directly from Astma-Allergi Denmark's data feed and turns it into structured, typed data objects.

The returned data shows the measured pollen between 13:00 (UTC +1) (1:00 PM) yesterday and 13:00 (UTC +1) (1:00 PM) present day. Every day at 16:30 (UTC +1) (4:30 PM), at the latest, the new measurements are being published.

⚠️ Disclaimer

Since Astma-Allergi Denmark is an independent union, with a very little government funding, this package is made available under a very strict license, which prohibits any use other than personal.

If you wish to use the pollen measurements commercially, you should contact Astma-Allergi Denmark directly and support them by buying the data instead. The payment goes directly to the maintenance and further development of their Pollen measurement service.

For more info about a commercial license, visit their official website.

📖 Table of contents

• Requirements
• Installation
  • Laravel
• Usage
  • Pollen Client
  • Methods
    • Get measurements
  • Return data structure
• Pollen stations
• Allergens
  • Icons
• Level classification
• Frequently Asked Questions (FAQ)
  • What is this Illuminate\Support\Collection class and how does it work?
• Donating to Astma-Allergi Denmark
• License

🖥 Requirements

• PHP 8.3 or higher
• GuzzleHTTP 7.0 or higher

📦 Installation

You can install the package via Composer, by using the following command:

composer require rugaard/pollen

Laravel

This package comes with an out-of-the-box Service Provider for the Laravel framework, which is loaded automatically via package discovery.

⚙️ Usage

First thing you need to do, is to instantiate the Pollen client:

use Rugaard\Pollen\Pollen;

$pollen = new Pollen;

Once you've done that, you're ready to fetch the latest measurements.

Pollen client

The Pollen client which handles the requests to Astma-Allergi Denmark.

new Pollen(?GuzzleClientInterface $client = null);

Methods

Get measurements

Get the latest pollen measurements and predictions. Optionally filter by station and/or exclude allergens that are currently out of season.

get(?Station $station = null, bool $onlyInSeason = false): Collection

Note: The returned data shows the measured pollen between 13:00 (1:00 PM) yesterday and 13:00 (1:00 PM) present day. The measurements are updated everyday at 16:00 (4:00 PM).

Examples:

use Rugaard\Pollen\Enums\Station;
use Rugaard\Pollen\Pollen;

$pollen = new Pollen;

# All stations.
$measurements = $pollen->get();

# A specific station.
$measurements = $pollen->get(station: Station::East);

# A specific station, in-season allergens only.
$measurements = $pollen->get(station: Station::East, onlyInSeason: true);

Return data structure

Single station

When a $station is provided, get() returns a Collection keyed by allergen code. Each value is either a Collection with measurement data, or null if the allergen is currently out of season.

$measurements = $pollen->get(station: Station::East);

// Access a specific allergen.
$birch = $measurements->get('birch');

// $birch is a Collection:
// [
//     'date'        => '2024-04-01',        // measurement date
//     'value'       => 200,                 // raw grain count
//     'level'       => Level::High,         // classified level enum
//     'predictions' => Collection [         // null for spore allergens
//         ['date' => '2024-04-02', 'level' => Level::Moderate],
//         ['date' => '2024-04-03', 'level' => Level::Low],
//     ],
// ]

// Out-of-season allergens are null.
$mugwort = $measurements->get('mugwort'); // null

All stations

When no $station is provided, get() returns a Collection keyed by station value ('east', 'west'), where each entry contains the station's allergen measurements as described above.

$measurements = $pollen->get();

$east = $measurements->get('east'); // Collection of allergens for Station::East
$west = $measurements->get('west'); // Collection of allergens for Station::West

🏛 Pollen stations

Currently there only exist two pollen stations in Denmark.

🌿 Allergens

The following allergens are supported. Spore allergens do not have predictions.

🖼 Icons

The assets/ folder contains a PNG icon for each allergen, named after its code.

Icon	Allergen
	alder
	hazel
	elm
	birch
	grass
	mugwort
	alternaria
	cladosporium

📊 Level classification

Each allergen measurement is classified into one of five levels, represented by the Level enum. Thresholds vary per allergen.

use Rugaard\Pollen\Enums\Level;

$birch = $measurements->get('birch');

// Compare against a level.
if ($birch->get('level') === Level::VeryHigh) {
    // 🤧
}

// Get a machine-readable code.
$birch->get('level')->code(); // e.g. 'very-high'

// Get the Danish name.
$birch->get('level')->danishName(); // e.g. 'meget højt'

🗣 Frequently Asked Questions (FAQ)

What is this Illuminate\Support\Collection class and how does it work?

All data is returned within an Illuminate\Support\Collection. This is the same Collection class used by the Laravel framework, available as a standalone package — so no Laravel installation is required.

Please refer to Laravel's detailed documentation to learn more about how you work with a Collection:
https://laravel.com/docs/collections

💰 Donating to Astma-Allergi Denmark

To help Astma-Allergi Denmark maintain and further develop the Pollen measurement service.
Please consider sending them a donation.

🚓 License

This package is licensed under a Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 (CC BY-NC-ND 4.0).