knmy - A simple Python wrapper for Dutch weather data from KNMI

https://travis-ci.org/barthoekstra/knmy.svg?branch=master https://coveralls.io/repos/github/barthoekstra/knmy/badge.svg?branch=master Documentation Status https://badge.fury.io/py/knmy.svg

knmy is a Python package for downloading and processing weather data from the automated weather stations of the Dutch Meteorological Institute (KNMI). Documentation of the used API can be found here (only in Dutch).

Contents

License

Copyright (c) 2022, Bart Hoekstra All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
  3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Developer

Changelog

Version 1.5.1

Updated to work with changes to KNMI API.

Data that can be requested via the API has remained the same, but there are several noteworthy changes

  • API endpoints have been updated.
  • Station names are not included in the dataframes by default anymore, instead only the station number is given. The parser still outputs a dataframe with station names and respective numbers, so they can still be linked.
  • The metadata provided by the KNMI for several variables and API endpoints has changed, sometimes dramatically. Unfortunately the documentation on the KNMI website does not fully reflect what the API provides anymore.
  • The previous version of the parser was fairly flexible, but the new version unfortunately relies on parsing hard-coded ‘blocks’ of information, because of some small inconsistencies. Unfortunately this also means minor changes to the formatting by KNMI will break the functionality of the parser again (but not data download).

If somehow the parser or other functionalities stop working, don’t hesitate to open an issue on GitHub.

Version 1.0.0

Initial release.

Usage

The main function is get_knmi_data(), which requires at minimum a type (first argument) to function. You can choose from:

  1. type = 'daily', which returns the daily aggregate weather data of all selected weather variables.
  2. type = 'hourly', which returns the hourly aggregate weather data of all selected weather variables.
  3. type = 'daily_rain', which always returns only the daily rain and snow cover data.

For convenience you have access to three wrapper functions that correspond to each of the aforementioned types: get_daily_data(), get_hourly_data() and get_daily_rain_data()

Example usage

from knmy import knmy

# Return daily aggregated wind, temperature and sunshine duration data for station 209 (IJmond) for the 1st til
# 6th of January, 2017
knmy.get_daily_data(stations=[209], start=20170101, end=20170106, variables=['WIND','TEMP', 'SQ'])

# Return dataframe with hourly wind and temperature data for station 209 (IJmond) and 235 (De Kooy) for the 1st
# til 6th of January of the years 2015 til 2017 for the 8th til 20th hour of the day
disclaimer, stations, variables, data = knmy.get_hourly_data(stations=[209, 235], start=2015010108, end=2017010620,
                                                             inseason=True, variables=['WIND', 'TEMP'], parse=True)

# Return dataframe with daily rain data for all stations for January 1st, 2017
disclaimer, variables, data = knmy.get_daily_rain_data(start=20170101, end=20170101, parse=True)

Function parameters

stations should contain a list of weather station numbers. To find out which weather stations are available for use, use the function without setting any stations (but with a start and end set), the function will then return a variable stations which contains a list of stations for which data is available for that period.

start and end are either an integer or datetime object (datetime.date for get_daily_data and datetime.datetime for get_hourly_data. If hourly data is requested, data is always returned starting from the hour set in start until the hour set in end. In case an integer is provided, make sure the first hour of the day (00:00-01:00) is hour 1 and the last hour of the day (23:00-24:00) is hour 24. To request overnight data — such as from 22:00 til 06:00 the next morning — use for example start=2017010123 and end=2017010507.

variables should contain a list of variables, and if none are specified returns all recorded variables. Variables can be selected individually, but also in the groups below. If you are unsure of the available variables, use one of the functions without providing variables and read the unpacked list of variables (see Example usage).

Variable groups:

  • ALL = All variables (Default)
  • WIND = DDVEC:FG:FHX:FHX:FX Wind
  • TEMP = TG:TN:TX:T10N Temperature
  • SUNR = SQ:SP:Q Sunshine
  • PRCP = DR:RH:EV24 Precipitation and potential evaporation
  • PRES = PG:PGX:PGN Pressure at sea level
  • VICL = VVN:VVX:NG Visibility and cloud cover
  • MSTR = UG:UX:UN Humidity

inseason is a boolean. If set to True, the function will only return data within the month-date combination for all given years (see Example usage).

parse is a boolean. If set to True, the function will parse the KNMI output data and return a disclaimer, measured variables, data and a list of stations.