frost-client

Build Status Documentation Status

This Python client wraps the Frost API. You should read up on those docs before using this client. And be sure to check out met.no’s Terms of Use

The main purpose of this client is returns Pandas Dataframes from Frost API data.

This is an unofficial client. We have no relationship to met.no

Documentation: https://frost-client.readthedocs.io/en/latest/

Install

Requires Python 3.7

pip install frost-client

or if you want the response from the API returned as Pandas DataFrame, use:

pip install frost-client[pandas]

or using pipenv:

pipenv install frost-client[pandas]

Note about zsh: If you’re using zsh add unsetopt nomatchto your .zshrc

Usage

The Frost API key should be exposed as a environment variable:

FROST_API_KEY=xxxxxx

or passed as a username parameter when creating and instance of the class.

Get weather data sources

Get all available observation sources (stations) for Hordaland county (12)

from frost.client import APIError, Frost
f = Frost()
res = f.get_sources(county='12')

# return as Pandas Dataframe (requires Pandas installed)
df = res.to_df()

# return IDs of sources as list
ids = res.to_ids_list()

Get available time series

Display available time series for a station (here Bergen - Florida)

from frost.client import APIError, Frost
f = Frost()
res = f.get_available_timeseries(sources=['SN50540'])

# return as Pandas Dataframe
df = res.to_df()

Get observations

Display observations for a station (here Bergen - Florida)

from frost.client import APIError, Frost
f = Frost()
res = f.get_observations(
            sources=['SN50540'],
            elements=['sum(precipitation_amount P1D)'],
            timeoffsets=['PT6H'],
            referencetime='2018-01-01/2018-02-01')
df = res.to_df()

See tests for more examples.

Local development

You should use pipenv

Tests

Enable the pipenv with

pipenv shell

Make sure to export env variable

FROST_API_KEY=xxxxxx

To run all tests:

nosetests

To run specific tests:

nosetests tests.test_requests:TestFrostRequests.test_get_sources

Client API reference

exception frost.client.APIError(e)[source]

Raised when the API responds with a 400 og 404

class frost.client.Frost(username=None)[source]

Interface to frost.met.no API

The Frost API key should be exposed as a environment variable called

FROST_API_KEY

or passed as a username parameter when creating and instance of the class.

>>>  frost = Frost(username="myapikey")
get_available_timeseries(include_sourcemeta=False, **kwargs)[source]

Find timeseries metadata by source and/or element

Parameters:
  • include_sourcemeta (bool) – If True will return a tuple with time series and source meta.
  • sources (list/str) – The ID(s) of the data sources to get time series for
  • referencetime (str) – The time range to get time series for as extended ISO-8601 format.
  • elements (list/str) – The elements to get time series for as a list of Element ids.
  • timeoffsets (list/str) – The time offsets to get time series for as a list of ISO-8601 periods, e.g. ‘PT6H,PT18H’. If left out, the output is not filtered on time offset.
  • timeresolutions (list/str) – The time resolutions to get time @ series for as a list of ISO-8601 periods, e.g. ‘PT6H,PT18H’. If left out, the output is not filtered on time resolution.
  • timeseriesids (str) – The internal time series IDs to get time @ series for as a list of integers, e.g. ‘0,1’. If left out, the output is not filtered on internal time series ID.
  • performancecategories (str) – The performance categories to get time series for as a list of letters, e.g. ‘A,C’. If left out, the output is not filtered on performance category.
  • exposurecategories (str) – The exposure categories to get time series for as a list of integers, e.g. ‘1,2’. If left out, the output is not filtered on exposure category.
  • levels (str) – The sensor levels to get observations for as a list of numbers, e.g. ‘0.1,2,10,20’. If left out, the output is not filtered on sensor level.
  • level_types (str) – The sensor level types to get records for as a list of search filters
  • level_units (str) – The sensor level units to get records for as a list of search filters
  • fields (str) – Fields to include in the output as a list. If specified, only these fields are included in the output. If left out, all fields are included.
Returns:

AvailableTimeSeriesResponse()

Raises:

APIError – raises exception if error in the returned data or not found.

get_observations(include_sourcemeta=False, **kwargs)[source]

Get observation data from the Frost API.

Parameters:
  • include_sourcemeta (bool) – If True will return a tuple with time series and source meta.
  • sources (list/str) – The ID(s) of the data sources to get observations for as a list of Frost API station IDs, e.g. _SN18700_ for Blindern.
  • referencetime (str) – The time range to get observations for in either extended ISO-8601 format or the single word ‘latest’.
  • elements (list/str) – The elements to get observations for as a list of names that follow the Frost API naming convention.
  • format (str) – The output format of the result. (required)
  • maxage (str) – The maximum observation age as an ISO-8601 period, like ‘P1D’. Applicable only when referencetime=latest. In general, the lower the value of maxage, the shorter the request will take to complete. The default value is ‘PT3H’.
  • limit (str) – The maximum number of observation times to be returned for each source/element combination, counting from the most recent time. Applicable only when referencetime=latest. Specify either ‘all’ to get all available times, or a positive integer. The default value is 1.
  • timeoffsets (list/str) – The time offsets to get observations for as a list of ISO-8601 periods, e.g. ‘PT6H,PT18H’. If left out, the output is not filtered on time offset.
  • timeresolutions (list/str) – The time resolutions to get observations for as a list of ISO-8601 periods, e.g. ‘PT6H,PT18H’. If left out, the output is not filtered on time resolution.
  • timeseriesids (str) – The internal time series IDs to get observations for as a list of integers, e.g. ‘0,1’. If left out, the output is not filtered on internal time series ID.
  • performancecategories (str) – The performance categories to get observations for as a list of letters, e.g. ‘A,C’. Enter a list to specify multiple performance categories. If left out, the output is not filtered on performance category.
  • exposurecategories (str) – The exposure categories to get observations for as a list of integers, e.g. ‘1,2’. If left out, the output is not filtered on exposure category.
  • levels (str) – The sensor levels to get observations for as a list of numbers, e.g. ‘0.1,2,10,20’. If left out, the output is not filtered on sensor level.
  • fields (str) – Fields to include in the output as a list. If specified, only these fields are included in the output. If left out, all fields are included.
Returns:

ObservationsResponse()

Raises:

APIError – raises exception if error in the returned data or not found.

get_sources(**kwargs)[source]

Get metadata for the source entitites defined in the Frost API. Use the query parameters to filter the set of sources returned.

Parameters:
  • ids (str) – The Frost API source ID(s) that you want metadata for. Enter a list or Python list to select multiple sources.
  • types (str) – The type of Frost API source that you want metadata for.
  • geometry (str) – Get Frost API sources defined by a specified geometry. Geometries are specified as either nearest(POINT(…)) or POLYGON(…)
  • nearestmaxcount (str) – The maximum number of sources returned when using nearest(POINT(…)) for geometry. The default value is 1.
  • validtime (str) – If specified, only sources that have been, or still are, valid/applicable during some part of this interval may be included in the result. Specify date/date;, date/now, dategt or now, where dategt is of the form YYYY-MM-DD, e.g. 2017-03-06. The default is ‘now’, i.e. only currently valid/applicable sources are included.
  • name (str) – If specified, only sources whose ‘name’ attribute matches this
  • country (str) – If specified, only sources whose ‘country’ or ‘countryCode’ attribute matches this
  • county (str) – If specified, only sources whose ‘county’ or ‘countyId’ attribute matches this .
  • municipality (str) – If specified, only sources whose ‘municipality’ or ‘municipalityId’ attribute matches this
  • wmoid (str) – If specified, only sources whose ‘wmoId’ attribute matches this
  • stationholder (str) – If specified, only sources whose ‘stationHolders’ attribute contains at least one name that matches this
  • externalid (str) – If specified, only sources whose ‘externalIds’ attribute contains at least one name that matches this
  • fields (str) – A list of the fields that should be present in the response.
Returns:

SourcesResponse()

Raises:

APIError – raises exception if error in the returned data or not found.

Examples:
>>> f = Frost()
>>> f.get_sources(county='12')
make_request(method, **kwargs)[source]

Make an API request, with all kwargs passed through as URL params

class frost.client.APIError(e)[source]

Raised when the API responds with a 400 og 404

class frost.client.Frost(username=None)[source]

Interface to frost.met.no API

The Frost API key should be exposed as a environment variable called

FROST_API_KEY

or passed as a username parameter when creating and instance of the class.

>>>  frost = Frost(username="myapikey")
get_available_timeseries(include_sourcemeta=False, **kwargs)[source]

Find timeseries metadata by source and/or element

Parameters:
  • include_sourcemeta (bool) – If True will return a tuple with time series and source meta.
  • sources (list/str) – The ID(s) of the data sources to get time series for
  • referencetime (str) – The time range to get time series for as extended ISO-8601 format.
  • elements (list/str) – The elements to get time series for as a list of Element ids.
  • timeoffsets (list/str) – The time offsets to get time series for as a list of ISO-8601 periods, e.g. ‘PT6H,PT18H’. If left out, the output is not filtered on time offset.
  • timeresolutions (list/str) – The time resolutions to get time @ series for as a list of ISO-8601 periods, e.g. ‘PT6H,PT18H’. If left out, the output is not filtered on time resolution.
  • timeseriesids (str) – The internal time series IDs to get time @ series for as a list of integers, e.g. ‘0,1’. If left out, the output is not filtered on internal time series ID.
  • performancecategories (str) – The performance categories to get time series for as a list of letters, e.g. ‘A,C’. If left out, the output is not filtered on performance category.
  • exposurecategories (str) – The exposure categories to get time series for as a list of integers, e.g. ‘1,2’. If left out, the output is not filtered on exposure category.
  • levels (str) – The sensor levels to get observations for as a list of numbers, e.g. ‘0.1,2,10,20’. If left out, the output is not filtered on sensor level.
  • level_types (str) – The sensor level types to get records for as a list of search filters
  • level_units (str) – The sensor level units to get records for as a list of search filters
  • fields (str) – Fields to include in the output as a list. If specified, only these fields are included in the output. If left out, all fields are included.
Returns:

AvailableTimeSeriesResponse()

Raises:

APIError – raises exception if error in the returned data or not found.

get_observations(include_sourcemeta=False, **kwargs)[source]

Get observation data from the Frost API.

Parameters:
  • include_sourcemeta (bool) – If True will return a tuple with time series and source meta.
  • sources (list/str) – The ID(s) of the data sources to get observations for as a list of Frost API station IDs, e.g. _SN18700_ for Blindern.
  • referencetime (str) – The time range to get observations for in either extended ISO-8601 format or the single word ‘latest’.
  • elements (list/str) – The elements to get observations for as a list of names that follow the Frost API naming convention.
  • format (str) – The output format of the result. (required)
  • maxage (str) – The maximum observation age as an ISO-8601 period, like ‘P1D’. Applicable only when referencetime=latest. In general, the lower the value of maxage, the shorter the request will take to complete. The default value is ‘PT3H’.
  • limit (str) – The maximum number of observation times to be returned for each source/element combination, counting from the most recent time. Applicable only when referencetime=latest. Specify either ‘all’ to get all available times, or a positive integer. The default value is 1.
  • timeoffsets (list/str) – The time offsets to get observations for as a list of ISO-8601 periods, e.g. ‘PT6H,PT18H’. If left out, the output is not filtered on time offset.
  • timeresolutions (list/str) – The time resolutions to get observations for as a list of ISO-8601 periods, e.g. ‘PT6H,PT18H’. If left out, the output is not filtered on time resolution.
  • timeseriesids (str) – The internal time series IDs to get observations for as a list of integers, e.g. ‘0,1’. If left out, the output is not filtered on internal time series ID.
  • performancecategories (str) – The performance categories to get observations for as a list of letters, e.g. ‘A,C’. Enter a list to specify multiple performance categories. If left out, the output is not filtered on performance category.
  • exposurecategories (str) – The exposure categories to get observations for as a list of integers, e.g. ‘1,2’. If left out, the output is not filtered on exposure category.
  • levels (str) – The sensor levels to get observations for as a list of numbers, e.g. ‘0.1,2,10,20’. If left out, the output is not filtered on sensor level.
  • fields (str) – Fields to include in the output as a list. If specified, only these fields are included in the output. If left out, all fields are included.
Returns:

ObservationsResponse()

Raises:

APIError – raises exception if error in the returned data or not found.

get_sources(**kwargs)[source]

Get metadata for the source entitites defined in the Frost API. Use the query parameters to filter the set of sources returned.

Parameters:
  • ids (str) – The Frost API source ID(s) that you want metadata for. Enter a list or Python list to select multiple sources.
  • types (str) – The type of Frost API source that you want metadata for.
  • geometry (str) – Get Frost API sources defined by a specified geometry. Geometries are specified as either nearest(POINT(…)) or POLYGON(…)
  • nearestmaxcount (str) – The maximum number of sources returned when using nearest(POINT(…)) for geometry. The default value is 1.
  • validtime (str) – If specified, only sources that have been, or still are, valid/applicable during some part of this interval may be included in the result. Specify date/date;, date/now, dategt or now, where dategt is of the form YYYY-MM-DD, e.g. 2017-03-06. The default is ‘now’, i.e. only currently valid/applicable sources are included.
  • name (str) – If specified, only sources whose ‘name’ attribute matches this
  • country (str) – If specified, only sources whose ‘country’ or ‘countryCode’ attribute matches this
  • county (str) – If specified, only sources whose ‘county’ or ‘countyId’ attribute matches this .
  • municipality (str) – If specified, only sources whose ‘municipality’ or ‘municipalityId’ attribute matches this
  • wmoid (str) – If specified, only sources whose ‘wmoId’ attribute matches this
  • stationholder (str) – If specified, only sources whose ‘stationHolders’ attribute contains at least one name that matches this
  • externalid (str) – If specified, only sources whose ‘externalIds’ attribute contains at least one name that matches this
  • fields (str) – A list of the fields that should be present in the response.
Returns:

SourcesResponse()

Raises:

APIError – raises exception if error in the returned data or not found.

Examples:
>>> f = Frost()
>>> f.get_sources(county='12')
make_request(method, **kwargs)[source]

Make an API request, with all kwargs passed through as URL params

class frost.models.SourcesResponse(sources_json)[source]

Response object for source endpoint

to_df(compact=False)[source]

Returns a Pandas DataFrame representation of the model

Parameters:compact (bool) – If True returns a compact version with fewer columns
to_ids_list()[source]

Returns only station IDs as a Python list

to_list()[source]

Returns the sources as a Python list of dicts

to_str()[source]

Returns the string representation of the data

class frost.models.ObservationsResponse(series_json, sources=None)[source]
get_source_ids()[source]

Returns unique source ids as a list

to_df(compact=False)[source]

Returns a Pandas DataFrame representation of the model

Parameters:
  • compact (bool) – If True returns a compact version with fewer columns
  • include_sourcemeta (bool) – If True will join in metadata (name etc) about the sources fewer columns
to_ids_list()[source]

Returns only station IDs as a Python list

to_list()[source]

Returns the sources as a Python list of dicts

to_str()[source]

Returns the string representation of the data

class frost.models.AvailableTimeSeriesResponse(series_json, sources=None)[source]
get_source_ids()[source]

Returns unique source ids as a list

to_df(compact=False)[source]

Returns a Pandas DataFrame representation of the model

Parameters:
  • compact (bool) – If True returns a compact version with fewer columns
  • include_sourcemeta (bool) – If True will join in metadata (name etc) about the sources fewer columns
to_ids_list()[source]

Returns only station IDs as a Python list

to_list()[source]

Returns the sources as a Python list of dicts

to_str()[source]

Returns the string representation of the data