frost-client¶
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 nomatch
to 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¶
-
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')
-
-
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
-
class
frost.models.
ObservationsResponse
(series_json, sources=None)[source]¶
-
class
frost.models.
AvailableTimeSeriesResponse
(series_json, sources=None)[source]¶