Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.
Awesome Lists | Featured Topics | Projects
https://github.com/rugaard/dmi

🇩🇰🌤 API for the Danish Meteorological Institute (DMI).
https://github.com/rugaard/dmi
api danish-meteorological-institute danmarks-meteorologiske-institut dmi dmi-api forecast meteorology weather weather-data
Last synced: about 2 months ago
JSON representation
🇩🇰🌤 API for the Danish Meteorological Institute (DMI).
Host: GitHub
URL: https://github.com/rugaard/dmi
Owner: rugaard
License: other
Created: 2019-07-09T15:21:20.000Z (over 5 years ago)
Default Branch: master
Last Pushed: 2024-06-16T19:32:55.000Z (7 months ago)
Last Synced: 2024-09-17T18:46:53.977Z (3 months ago)
Topics: api, danish-meteorological-institute, danmarks-meteorologiske-institut, dmi, dmi-api, forecast, meteorology, weather, weather-data
Language: PHP
Homepage: https://github.com/rugaard/dmi
Size: 353 KB
Stars: 14
Watchers: 3
Forks: 1
Open Issues: 0
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project

README

        


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











The Danish Meteorological Institute (DMI) does unfortunately not offer an official API ([yet](#%EF%B8%8F-disclaimer)). 

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](https://github.com/rugaard/dmi/issues/new) 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](#-features)

* [Installation](#-installation)

    * [Laravel](#laravel)

* [Usage](#%EF%B8%8F-usage)

    * [DMI Client](#dmi-client)

    * [Methods](#methods)

        * [National forecast](#national-forecast)

        * [Extended national forecast](#extended-national-forecast) 

        * [Search locations](#search-locations)

        * [Location by ID](#location-by-id)

        * [Location by coordinate](#location-by-coordinate)

        * [Weather warnings](#weather-warnings)

        * [Sun times](#sun-times)

        * [UV index](#uv-index)

        * [Pollen](#pollen)

        * [Sea stations](#sea-stations)

        * [Sea station by ID](#sea-station-by-id)

        * [Archived weather data](#archived-weather-data)

* [Icons](#-icons)

    * [Day](#day-after-sunrise)

    * [Night](#night-after-sunset)

* [Municipalities](#-municipalities)

* [Frequently Asked Questions (FAQ)](#-frequently-asked-questions-faq)

    * [How do I find the ID of a pre-defined location?](#how-do-i-find-the-id-of-a-pre-defined-location)

    * [What is this `Tightenco\Collect\Support\Collection` class and how does it work?](#what-is-this-tightencocollectsupportcollection-class-and-how-does-it-work)

* [Roadmap](#-roadmap)

    * [Internal caching](#internal-caching)

* [License](#-license)

## 🚀 Features

| Name | Description | Supported |

| :--- | :--- | :---: |

| National forecasts | National descriptive forecasts (incl. 7 days forecast) | ✅ |

| Search | Search pre-defined locations | ✅ |

| Location | Weather data/forecast for a pre-defined location | ✅ |

| Location by coordinate | Weather data/forecast for a location based on coordinates _(latitude/longitude)_ | ✅ |

| Weather warnings | National weather warnings | ✅ |

| Sun times | Time of sunrise and sunset | ✅ |

| UV index | Current UV index | ✅ |

| Pollen | Current Pollen measurements | ✅ |

| Sea stations | All national sea stations and their observations and forecasts | ✅ |

| Sea station by ID | Observations and forecasts from a specific sea station | ✅ |

| Archive | Hourly, daily, monthly and yearly data from the DMI archive | ✅ |

| Satellite | Satellite imagery | ❌ |

| Maritime forecasts | Forecasts around the coasts of Denmark, Greenland & Faroe Islands | ❌ |

| Ice charts | Ice charts along the coasts of Greenland | ❌ |

## 📦 Installation

You can install the package via [Composer](https://getcomposer.org/), by using the following command:

```shell

composer require rugaard/dmi

```

### Laravel

This package comes with a out-of-the-box Service Provider for the [Laravel](http://laravel.com) 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:

```php

'providers' => [

    Rugaard\DMI\Providers\Laravel\ServiceProvider::class,

]

```

## ⚙️ Usage

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

```php

# 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:

```php

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

```php

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

```

| Parameter | Type | Default | Description |

| :--- | :--- | :---: | :--- |

| `$defaultLocationId` | `int` | `null` | Set default location ID |

| `$httpClient` | `\GuzzleHttp\ClientInterface` | `null` | Replace the default underlying HTTP Client |

### Methods

#### National forecast

Get the latest national descriptive forecast.

```php

forecast();

```

#### Extended national forecast

Get the extended (_7-days_) national descriptive forecast.

```php

extendedForecast();

```

#### Search locations

Search locations by name.

```php

search(string $query, int $limit);

```

| Parameter | Type | Default | Description |

| :--- | :--- | :---: | :--- |

| `$query` | `string` | - | Search query |

| `$limit` | `int` | `20` | Max. number of locations to return. |

#### 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._

```php

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

```

| Parameter | Type | Default | Description |

| :--- | :--- | :---: | :--- |

| `$locationId` | `int` | `null` | ID of location _(If `null`, it'll use the default location ID from the `DMI` client.)_ |

| `$includeRegional` | `bool` | `true` | Include regional data and forecast for location `*` |

| `$includeWarnings` | `bool` | `true` | Include weather warnings specific for location `*` |

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

```php

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

```

| Parameter | Type | Default | Description |

| :--- | :--- | :---: | :--- |

| `$latitude` | `float` | - | Latitude part of coordinate |

| `$longitude` | `float` | - | Longitude part of coordinate |

| `$includeRegional` | `bool` | `true` | Include regional data and forecast for location `*` |

| `$includeWarnings` | `bool` | `true` | Include weather warnings specific for location `*` |

_`*` Makes additional request to DMI._

#### Weather warnings

Get national weather warnings.

```php

warnings();

```

#### Sun times

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

```php

sunTimes(?int $locationId);

```

| Parameter | Type | Default | Description |

| :--- | :--- | :---: | :--- |

| `$locationId` | `int` | `null` | ID of location _(If `null`, it'll use the default location ID from the `DMI` client.)_  |

#### UV index

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

```php

uv(?int $locationId);

```

| Parameter | Type | Default | Description |

| :--- | :--- | :---: | :--- |

| `$locationId` | `int` | `null` | ID of location _(If `null`, it'll use the default location ID from the `DMI` client.)_  |

#### Pollen

Get the current national pollen measurements.

```php

pollen();

```

#### Sea stations

Get all sea stations belonging to DMI.

```php

seaStations(bool $withObservations, bool $withForecast);

```

| Parameter | Type | Default | Description |

| :--- | :--- | :---: | :--- |

| `$withObservations` | `bool` | `false` | Include observation data from each station `*` |

| `$withForecast` | `bool` | `false` | Include forecast data for each station `*` |

_`*` Makes additional request to DMI._

#### Sea station by ID

Get a specific sea stations.

```php

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

```

| Parameter | Type | Default | Description |

| :--- | :--- | :---: | :--- |

| `$stationId` | `int` | - | ID of sea station |

| `$withObservations` | `bool` | `false` | Include observation data from each station `*` |

| `$withForecast` | `bool` | `false` | Include forecast data for each station `*` |

_`*` Makes additional request to DMI._

#### Archived weather data

Get archived weather data.

```php

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

```

| Parameter | Type | Default | Description |

| :--- | :--- | :---: | :--- |

| `$measurement` | `string` | - | `temperature`, `precipitation`, `wind`, `wind-direction`, `humidity`, `pressure`, `sun`, `drought`, `lightning` or `snow` |

| `$frequency` | `string` | - | `hourly`, `daily`, `monthly` or `yearly` |

| `$period` | `string` or `DateTime` | - | `hourly`/`daily` = `YYYY-mm-dd`, `monthly` = `YYYY-mm`
or `yearly` = `YYYY` |

| `$municipalityId` | `int` | `null` | Limit archived data to a specific municipality. [See the full list of available municipality IDs](#-municipalities) |

| `$country` | `string` | `DK` | `DK` = Denmark, `GL` = Greenland, `FO` = Faroe Islands |

## 🌤 Icons

When getting weather data from a [location](#location-by-id), 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](https://www.flaticon.com/packs/weather-97), 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.

| Name | ID | Name | ID | Name | ID | Name | ID |

| :--- | :---: | :--- | :---: | :--- | :---: | :--- | :---: |

| Albertslund | 165 | Allerød | 201 | Assens | 420 | Ballerup | 151 |

| Billund | 530 | Bornholm | 400 | Brøndby | 153 | Brønderslev | 810 |

| Dragør | 155 | Egedal | 240 | Esbjerg | 561 | Fanø | 563 |

| Favrskov | 710 | Faxe | 320 | Fredensborg | 210 | Fredericia | 607 |

| Frederiksberg | 147 | Frederikshavn | 813 | Frederikssund | 250 | Furesø | 190 |

| Faaborg-Midtfyn | 430 | Gentofte | 157 | Gladsaxe | 159 | Glostrup | 161 |

| Greve | 253 | Gribskov | 270 | Guldborgsund | 376 | Haderslev | 510 |

| Halsnæs | 260 | Hedensted | 766 | Helsingør | 217 | Herlev | 163 |

| Herning | 657 | Hillerød | 219 | Hjørring | 860 | Holbæk | 316 |

| Holstebro | 661 | Horsens | 615 | Hvidovre | 167 | Høje-Taastrup | 169 |

| Hørsholm | 223 | Ikast-Brande | 756 | Ishøj | 183 | Jammerbugt | 849 |

| Kalundborg | 326 | Kerteminde | 440 | Kolding | 621 | København | 101 |

| Køge | 259 | Langeland | 482 | Lejre | 350 | Lemvig | 665 |

| Lolland | 360 | Lyngby-Taarbæk | 173 | Læsø | 825 | Mariagerfjord | 846 |

| Middelfart | 410 | Morsø | 773 | Norddjurs | 707 | Nordfyns | 480 |

| Nyborg | 450 | Næstved | 390 | Odder | 727 | Odense | 461 |

| Odsherred | 306 | Randers | 730 | Rebild | 840 | Ringkøbing-Skjern | 760 |

| Ringsted | 329 | Roskilde | 265 | Rudersdal | 230 | Rødovre | 175 |

| Samsø | 741 | Silkeborg | 740 | Skanderborg | 746 | Skive | 779 |

| Slagelse | 330 | Solrød | 269 | Sorø | 340 | Stevns | 336 |

| Struer | 671 | Svendborg | 479 | Syddjurs | 706 | Sønderborg | 540 |

| Thisted | 787 | Tønder | 550 | Tårnby | 185 | Vallensbæk | 187 |

| Varde | 573 | Vejen | 575 | Vejle | 630 | Vesthimmerland | 820 |

| Viborg | 791 | Vordingborg | 390 | Ærø | 492 | Aabenraa | 580 |

| Aalborg | 851 | Aarhus

## 🗣 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](#search-locations).

2. Go to [DMI's website](https://www.dmi.dk/) 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](https://laravel.com).

Please refer to [Laravel](https://laravel.com)'s detailed documentation, to learn more about how you work with a `Collection`:


[https://laravel.com/docs/master/collections](https://laravel.com/docs/master/collections)

## 🗺 Roadmap

#### Internal caching

Some endpoints, like [National forecasts](#national-forecast), [sunrise and sunset](#sun-times) and [pollen measurements](#pollen) 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)](https://creativecommons.org/licenses/by-nc-nd/4.0/).