README

🇩🇰🌤️ Danish Meteorological Institute (DMI) API.

The Danish Meteorological Institute (DMI) does unfortunately not offer an official API (yet).

This package is (in some form) a workaround for that. It collects all weather data (forecasts and archived) from the official DMI website and turns it into structured data objects.

Note: Since the data is being extracted from a the website, there is a risk of the package could stop working, if the website does any breaking changes.

Should this happen, please don't hesitate to create an issue and I will look into it as quickly as possible

⚠️ Disclaimer

As part of the danish governments desire to become one of the digital frontrunners, they have decided that the Danish Meteorological Institute (DMI) has to make all of their data available to the public.

The data will be released in multiple stages over the next 3 years, starting from Q3 in 2019 until Q4 in 2022. Unfortunately there is not much information on how the data will be released.

Depending on how the data will be released, this package will be subject to changes in the future.

Since the data is not officially released, this package is made available under a very strict license, which prohibits any use other than personal.

When DMI releases the data publicly, the license will be changed to a more open source-friendly (MIT) version.

📖 Table of contents

• Features
• Installation
  • Laravel
• Usage
  • DMI Client
  • Methods
    • National forecast
    • Extended national forecast
    • Search locations
    • Location by ID
    • Location by coordinate
    • Weather warnings
    • Sun times
    • UV index
    • Pollen
    • Sea stations
    • Sea station by ID
    • Archived weather data
• Icons
  • Day
  • Night
• Municipalities
• Frequently Asked Questions (FAQ)
  • How do I find the ID of a pre-defined location?
  • What is this Tightenco\Collect\Support\Collection class and how does it work?
• Roadmap
  • Internal caching
• License

🚀 Features

📦 Installation

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

composer require rugaard/dmi

Laravel

This package comes with a out-of-the-box Service Provider for the Laravel framework. If you're using a newer version of Laravel (>= 5.5) then the service provider will loaded automatically.

Are you using an older version, then you need to manually add the service provider to the config/app.php file:

'providers' => [
    Rugaard\DMI\Providers\Laravel\ServiceProvider::class,
]

⚙️ Usage

First thing you need to do, is to instantiate the DMI client

# Instantiate the DMI client.
$dmi = new \Rugaard\DMI\DMI;

Once you've done that, you're able to request one or more of the supported features:

# National forecast.
$forecast = $dmi->forecast();

# Location by coordinate.
$location = $dmi->locationByCoordinate(55.67594, 12.56553);

# National warnings.
$warnings = $dmi->warnings();

DMI client

The DMI client which handles all request DMI.

new DMI(?int $defaultLocationId, ?Client $httpClient);

Methods

National forecast

Get the latest national descriptive forecast.

forecast();

Extended national forecast

Get the extended (7-days) national descriptive forecast.

extendedForecast();

Search locations

Search locations by name.

search(string $query, int $limit);

Location by ID

Get current weather condition and latest forecast for a pre-defined location.

Note: $includeRegional is required to get municipality and region of location.

location(?int $locationId, bool $includeRegional, bool $includeWarnings);

* Makes additional request to DMI.

Location by coordinate

Get current weather condition and latest forecast for a location specified by coordinates.

Note: $includeRegional is required to get municipality and region of location.

locationByCoordinate(float $latitude, float $longitude, bool $includeRegional, bool $includeWarnings);

* Makes additional request to DMI.

Weather warnings

Get national weather warnings.

warnings();

Sun times

Get time of the sunrise and sunset, for the next 14 days, for a pre-defined location.

sunTimes(?int $locationId);

UV index

Get the current UV index for a pre-defined location.

uv(?int $locationId);

Pollen

Get the current national pollen measurements.

pollen();

Sea stations

Get all sea stations belonging to DMI.

seaStations(bool $withObservations, bool $withForecast);

* Makes additional request to DMI.

Sea station by ID

Get a specific sea stations.

seaStation(int $stationId, bool $withObservations, bool $withForecast);

* Makes additional request to DMI.

Archived weather data

Get archived weather data.

archive(string $measurement, string $frequency, $period, ?int $municipalityId, string $country);

🌤 Icons

When getting weather data from a location, the response will contain an $icon value. The purpose of this value is to determine which icon represents the current weather conditions.

In the table below is a list of all possible icons and values. Each icon is associated with a suggested emoji or image.

I would recommend downloading the free icon pack from Pixel Perfect, since it's one of the few ones, that both contains a day and night version of each condition - while still being free.

Day (after sunrise)

Condition	Value	Emoji	Image
Clear	clear	☀️
Partly cloudy	partly-cloudy	⛅️
Cloudy	cloudy	☁️
Foggy or misty	foggy	🌫
Thunderstorm	thunderstorm	️️ ⛈
Clear with light rain	clear-light-rain	️ 🌧
Light rain	light-rain	️ 🌧
Clear with heavy rain	clear-heavy-rain	️ 🌧
Heavy rain	heavy-rain	️ 🌧
Clear with light sleet	clear-light-sleet	️️ 🌨
Light sleet	light-sleet	️️ 🌨
Clear with heavy sleet	clear-heavy-sleet	️️ 🌨
Heavy sleet	heavy-sleet	️️ 🌨
Clear with light snow	clear-light-snow	️️ ☃️
Light snow	light-snow	️️ ☃️
Clear with heavy snow	clear-heavy-snow	️️ ☃️
Heavy snow	heavy-snow	️️ ☃️
Blowing snow	blowing-snow	️️ 🌬

Night (after sunset)

Condition	Value	Emoji	Icon
Clear	clear-night	🌕️
Partly cloudy	partly-cloudy-night	⛅️
Cloudy	cloudy-night	☁️
Foggy or misty	foggy-night	🌫
Thunderstorm	thunderstorm-night	️️ ⛈
Clear with light rain	clear-light-rain-night	️ 🌧
Light rain	light-rain-night	️ 🌧
Clear with heavy rain	clear-heavy-rain-night	️ 🌧
Heavy rain	heavy-rain-night	️ 🌧
Clear with light sleet	clear-light-sleet-night	️️ 🌨
Light sleet	light-sleet-night	️️ 🌨
Clear with heavy sleet	clear-heavy-sleet-night	️️ 🌨
Heavy sleet	heavy-sleet-night	️️ 🌨
Clear with light snow	clear-light-snow-night	️️ ☃️
Light snow	light-snow-night	️️ ☃️
Clear with heavy snow	clear-heavy-snow-night	️️ ☃️
Heavy snow	heavy-snow-night	️️ ☃️
Blowing snow	blowing-snow-night	️️ 🌬

🏛 Municipalities

Denmark is split into 98 municipalities. In the list below are all the municipalities and their corresponding ID.

🗣 Frequently Asked Questions (FAQ)

How do I find the ID of a pre-defined location?

There are two ways to find it:

1. Use this package's search endpoint.

2. Go to DMI's website and use the search feature in the top right corner. If your desired location pops up; click on it and you will be directed to the locations page. You can now copy/paste the ID from the locations URL.

https://www.dmi.dk/lokation/show/DK/2618425/København/

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

All endpoints returns data within a Tightenco\Collect\Support\Collection class. The class is a port of the popular Collection class from Laravel.

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

🗺 Roadmap

Internal caching

Some endpoints, like National forecasts, sunrise and sunset and pollen measurements are endpoints which doesn't change/update very often.

By implementing some form of internal caching, we could cache these kind of endpoints. This would increase the response time and we would avoid making unnecessary requests to DMI.

🚓 License

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