From ae385a9f89b51b7574d8aa754f6bf3bfdc12f339 Mon Sep 17 00:00:00 2001 From: clampr Date: Wed, 23 Jun 2021 14:30:43 +0200 Subject: [PATCH] Transfer API to RapidAPI --- src/.vuepress/config.js | 32 ++---- src/api/README.md | 29 ++--- src/api/point/README.md | 20 +--- src/api/point/climate.md | 181 ------------------------------- src/api/point/daily.md | 46 +++++--- src/api/point/hourly.md | 74 +++++++------ src/api/point/monthly.md | 93 ++++++++++++++++ src/api/point/normals.md | 83 ++++++++++++++ src/api/stations/README.md | 4 +- src/api/stations/climate.md | 179 ------------------------------ src/api/stations/daily.md | 38 ++++--- src/api/stations/hourly.md | 67 +++++++----- src/api/stations/meta.md | 104 ++++++++++++------ src/api/stations/monthly.md | 91 ++++++++++++++++ src/api/stations/nearby.md | 95 +++++++++------- src/api/stations/normals.md | 198 ++++++++++++++++++++++++++++++++++ src/api/stations/search.md | 142 ------------------------ src/api/wrapper/javascript.md | 152 -------------------------- src/bulk/stations.md | 3 + 19 files changed, 761 insertions(+), 870 deletions(-) delete mode 100644 src/api/point/climate.md create mode 100644 src/api/point/monthly.md create mode 100644 src/api/point/normals.md delete mode 100644 src/api/stations/climate.md create mode 100644 src/api/stations/monthly.md create mode 100644 src/api/stations/normals.md delete mode 100644 src/api/stations/search.md delete mode 100644 src/api/wrapper/javascript.md diff --git a/src/.vuepress/config.js b/src/.vuepress/config.js index be862a2..8534dc3 100755 --- a/src/.vuepress/config.js +++ b/src/.vuepress/config.js @@ -398,10 +398,6 @@ module.exports = { title: 'Overview', path: 'stations/' }, - { - title: 'Finding Stations', - path: 'stations/search' - }, { title: 'Nearby Stations', path: 'stations/nearby' @@ -418,9 +414,13 @@ module.exports = { title: 'Daily Data', path: 'stations/daily' }, + { + title: 'Monthly Data', + path: 'stations/monthly' + }, { title: 'Climate Normals', - path: 'stations/climate' + path: 'stations/normals' } ] }, @@ -441,28 +441,18 @@ module.exports = { path: 'point/daily' }, { - title: 'Climate Normals', - path: 'point/climate' - } - ] - }, - { - title: 'Wrapper', - collapsable: false, - children: [ - { - title: 'JavaScript', - path: 'wrapper/javascript' + title: 'Monthly Data', + path: 'point/monthly' }, { - title: 'PHP', - path: 'https://gitlab.com/dweipert.de/meteostat' + title: 'Climate Normals', + path: 'point/normals' } ] }, { - title: 'Get A Key', - path: 'https://auth.meteostat.net/' + title: 'Playground', + path: 'https://rapidapi.com/meteostat/api/meteostat/' } ] } diff --git a/src/api/README.md b/src/api/README.md index 48e8997..2729eb6 100644 --- a/src/api/README.md +++ b/src/api/README.md @@ -2,41 +2,42 @@ The Meteostat JSON API provides simple access to a large archive of historical weather and climate data. The records are queried by weather station or geo location and can be filtered by specifying a date range and other optional parameters. -::: tip Donation -Help Meteostat provide free weather and climate data by making a [donation](/contributing.html#donations). -::: +Meteostat uses [RapidAPI](https://rapidapi.com/meteostat/api/meteostat/), an API marketplace which makes it easy for developers to use thousands of APIs through a common platform. -The API is available via this URL: +This is the base URL for all endpoints: ``` -https://api.meteostat.net +https://meteostat.p.rapidapi.com ``` -Access to the API requires users to send their API key along with every request. All API endpoints return a JSON object that contains two properties: `meta` and `data`. The `meta` object provides general information about the data output and debugging information. For instance, the `source` string which holds the names of the organizations which provided the raw data. The `data` property is either an object or an array that contains the actual data output. +Access to the API requires users to send their RapidAPI key along with every request. All API endpoints return a JSON object that contains two properties: `meta` and `data`. The `meta` object provides general information about the data output and debugging information. The `data` property is either an object or an array that contains the actual data output. All API endpoints are accessible using HTTP Get requests. For debugging, please utilize the HTTP status code of the response. -## API Key +## Sign Up -Please submit this [**form**](https://auth.meteostat.net/) to apply for an API key. +Please sign up on [RapidAPI](https://rapidapi.com/signup) to get an API key. Before you can call the Meteostat JSON API, you'll need to subscribe to one of [our plans](https://rapidapi.com/meteostat/api/meteostat/pricing). But don't worry - you'll get 500 monthly calls for free. ## Quick Start Once you have your API key, head over to your terminal, replace the `{key}` parameter with your personal API key and execute the following command: ```sh -curl --header "x-api-key: {key}" "https://api.meteostat.net/v2/stations/meta?id=10637" +curl --request GET \ + --url 'https://meteostat.p.rapidapi.com/stations/meta?id=10637' \ + --header 'x-rapidapi-host: meteostat.p.rapidapi.com' \ + --header 'x-rapidapi-key: {key}' ``` You should see meta information for the weather station _Frankfurt Airport_ in JSON format. -## Quota +## Plans & Quota -Free access to the Meteostat API is limited to 2,000 requests per day and no more than two requests per second. Once this limit is reached, all of your requests will result in HTTP 429, too many requests, until your quota is cleared. +Meteostat uses a freemium model for its API. We offer a free plan with a hard limit of 500 requests per month. If you need a higher quota, please choose any of our [paid plans](https://rapidapi.com/meteostat/api/meteostat/pricing). ## Authentication -When retrieving data from Meteostat API endpoints make sure to send the `x-api-key` header along with every request. You cannot use the `key` URL parameter to authenticate API calls as in version 1. +When retrieving data from Meteostat API endpoints make sure to send the `X-RapidAPI-Key` header along with every request. RapidAPI also supports passing the API Key via query parameter. You can do this by including the `rapidapi-key` parameter in your request. ## Status Codes @@ -45,8 +46,8 @@ All Meteostat API endpoints return one of the following status codes. You can ut | **Code** | **Description** | |:---------|:-------------------------------------------------------------| | 200 | _Success_: Alls is fine | -| 400 | _Bad Request_: Please check the request parameters | -| 401 | _Unauthorized_: Make sure to send a valid `x-api-key` header | +| 400 | _Bad Request_: Please check the query parameters | +| 401 | _Unauthorized_: Make sure to send a valid RapidAPI key | | 403 | _Forbidden_: You're not allowed to access this endpoint | | 404 | _Not Found_: This endpoint doesn't exist | | 429 | _Too Many Requests_: You've exceeded the quota | diff --git a/src/api/point/README.md b/src/api/point/README.md index 9739091..8e3c8dc 100644 --- a/src/api/point/README.md +++ b/src/api/point/README.md @@ -8,26 +8,10 @@ While weather stations provide data that was measured at a specific location, po ## Remarks -Point data is currently considered an **experimental feature**. The way data is being interpolated is still subject to changes. Moreover, point data **only returns data if there is at least one nearby weather station** that reported observations in the desired period. The model output is by no means a substitute for actual observations. - -We encourage API users to give the new feature a try. Please get in touch with Meteostat for feedback and suggestions. +Point data **only returns data if there is at least one nearby weather station** that reported observations in the desired period. The model's quality is varying based on the number and proximity of nearby weather stations. ## Data Model Point data provides more complete time series, as observations of multiple stations are joined together. The data output is being interpolated based on the geographical distance between the different weather stations and the reference point of the query. Additionally, Meteostat adjusts measurements based on environmental circumstances and differences in altitude. -Meteostat projects the existing observations which are provided by weather stations around the world to the location specified in the request. Long-term climate averages are based on the incredible [WorldClim](https://worldclim.org/) project. For more precise model output, please provide the elevation of your location using the `alt` parameter. - -## Endpoints - -Meteostat provides three different endpoints for point data: - -* [Hourly Data](hourly.md) -* [Daily Data](daily.md) -* [Climate Normals](climate.md) - -## Vision - -The use cases for historical weather data are diverse. While actual observations of professional weather stations are crucial for science and research, model data provides a better coverage across the globe. Point data is an addition to the thousands of weather stations which are available through Meteostat. - -With a growing community of developers and contributors who are using and building Meteostat, we will be able to provide even better model output in the future. We are visioning a machine learning based approach for point data which allows our model to improve over time. +Meteostat projects the existing observations which are provided by weather stations around the world to the location specified in the request. For more precise model output, please provide the elevation of your location using the `alt` parameter. diff --git a/src/api/point/climate.md b/src/api/point/climate.md deleted file mode 100644 index 2b1d63a..0000000 --- a/src/api/point/climate.md +++ /dev/null @@ -1,181 +0,0 @@ ---- -title: Climate Normals | Point Data | JSON API ---- - -# Climate Normals - -Climate normals are long-term averages of historical weather observations. Usually, these means are calculated over a period of 30 years (“_reference period_“). However, any other time series of sufficient length can be used to calculate climate normals. - -Climate normals represent the typical monthly weather at a given location. The averages can also be used for calculating anomalies of current weather and climate conditions. - -## Endpoint - -Climate normals are provided through this endpoint: - -``` -GET https://api.meteostat.net/v2/point/climate -``` - -## Parameters - -In order to query data for any location you’ll need to specify the `lat` and `lon` parameters. You will probably also want to add the `alt` parameter to your request to make the output more precise. If you do not set the `alt` parameter, Meteostat will detect the elevation using its own elevation model. - -| **Parameter** | **Description** | **Type** | **Required** | **Default** | -|:--------------|:-----------------------------------------|:---------|:-------------|:------------| -| lat | The latitude of the geographic location | Float | Yes | `undefined` | -| lon | The longitude of the geographic location | Float | Yes | `undefined` | -| alt | The elevation of the geographic location | Integer | No | 0 | - -## Response - -The response body includes the following properties. - -| **Parameter** | **Description** | **Type** | -|:--------------|:-------------------------------------------|:---------| -| month | The integer number of the month (1 to 12) | Integer | -| tavg | The mean temperature in °C | Float | -| tmin | The average minimum temperature in °C | Float | -| tmax | The average maximum temperature in °C | Float | -| prcp | The average total precipitation in mm | Integer | -| pres | The average sea-level air pressure in hPa | Float | -| tsun | The average sunshine duration in hours (h) | Integer | - -More information about the data format is available [here](/formats.html). - -Additionally, the `meta` object includes the `start` and `end` year of the climate averages. - -## Example - -The following example requires the cURL command-line interface. Alternatively, you can use an API client like Postman. - -```sh -curl --header "x-api-key: {key}" "https://api.meteostat.net/v2/point/climate?lat=-33.87&lon=151.21&alt=58" -``` - -Please replace `{key}` with your personal API key. - -### Data Response - -The data output returns one object per month. Have a look at this example: - -```json -{ - "meta": { - "source": "National Oceanic and Atmospheric Administration, Deutscher Wetterdienst", - "start": 1961, - "end": 1990, - "exec_time": 0.015, - "generated": "2020-06-14 10:15:40" - }, - "data": [ - { - "month": 1, - "tavg": 0.7, - "tmin": null, - "tmax": null, - "prcp": 43.8, - "pres": 1018, - "tsun": 41 - }, - { - "month": 2, - "tavg": 1.8, - "tmin": null, - "tmax": null, - "prcp": 39.8, - "pres": 1017.5, - "tsun": 75 - }, - { - "month": 3, - "tavg": 5.2, - "tmin": null, - "tmax": null, - "prcp": 51.1, - "pres": 1014.9, - "tsun": 116 - }, - { - "month": 4, - "tavg": 9.2, - "tmin": null, - "tmax": null, - "prcp": 51.5, - "pres": 1014.2, - "tsun": 163 - }, - { - "month": 5, - "tavg": 13.7, - "tmin": null, - "tmax": null, - "prcp": 61.3, - "pres": 1014.6, - "tsun": 207 - }, - { - "month": 6, - "tavg": 17.1, - "tmin": null, - "tmax": null, - "prcp": 70.2, - "pres": 1015.6, - "tsun": 209 - }, - { - "month": 7, - "tavg": 18.9, - "tmin": null, - "tmax": null, - "prcp": 63, - "pres": 1016.6, - "tsun": 225 - }, - { - "month": 8, - "tavg": 18.3, - "tmin": null, - "tmax": null, - "prcp": 64.8, - "pres": 1016.1, - "tsun": 204 - }, - { - "month": 9, - "tavg": 14.8, - "tmin": null, - "tmax": null, - "prcp": 48.3, - "pres": 1018.3, - "tsun": 158 - }, - { - "month": 10, - "tavg": 9.8, - "tmin": null, - "tmax": null, - "prcp": 50.5, - "pres": 1017.6, - "tsun": 103 - }, - { - "month": 11, - "tavg": 4.7, - "tmin": null, - "tmax": null, - "prcp": 59.4, - "pres": 1018.3, - "tsun": 48 - }, - { - "month": 12, - "tavg": 1.8, - "tmin": null, - "tmax": null, - "prcp": 54.1, - "pres": 1016.9, - "tsun": 39 - } - ] -} -``` diff --git a/src/api/point/daily.md b/src/api/point/daily.md index 6ee95ee..481d60a 100644 --- a/src/api/point/daily.md +++ b/src/api/point/daily.md @@ -4,44 +4,55 @@ title: Daily Data | Point Data | JSON API # Daily Data -This endpoint provides historical daily statistics for a geographic location. The data provided through this endpoint is aggregated from multiple governmental interfaces. +This endpoint provides historical daily statistics for any geographic location. The data provided through this endpoint is aggregated from multiple governmental interfaces. -Daily data is coming in with an offset of about one to seven days. However, some data might be added multiple days or even months later, depending on how the different weather services are updating their datasets. Additionally, Meteostat provides daily aggregates based on hourly observations. +Daily data is coming in with an offset of about one to seven days. However, some data might be added multiple days or even months later, depending on when exactly the different weather services are updating their datasets. Additionally, Meteostat aggregates daily data from hourly observations and model data. -Daily data can be queried for a **maximum of 370 days** per request. +Daily data can be queried for a **maximum of 10 years** per request. ## Endpoint Daily data is provided through this endpoint: ``` -GET https://api.meteostat.net/v2/point/daily +GET https://meteostat.p.rapidapi.com/point/daily ``` ## Parameters -In order to query data for any location you’ll need to specify the `lat` and `lon` parameters. You will probably also want to add the `alt` parameter to your request to make the output more precise. If you do not set the `alt` parameter, Meteostat will detect the elevation using its own elevation model. +In order to query data for any location you’ll need to specify the `lat` and `lon` parameters. You will probably also want to add the `alt` parameter to your request to make the output more precise. If you do not set the `alt` parameter, Meteostat will guess the elevation based on nearby weather stations. -| **Parameter** | **Description** | **Type** | **Required** | **Default** | -|:--------------|:-------------------------------------------------|:---------|:-------------|:------------| -| lat | The latitude of the geographic location | Float | Yes | `undefined` | -| lon | The longitude of the geographic location | Float | Yes | `undefined` | -| alt | The elevation of the geographic location | Integer | No | 0 | -| start | The start date of the query (format: YYYY-MM-DD) | String | Yes | `undefined` | -| end | The end date of the query (format: YYYY-MM-DD) | String | Yes | `undefined` | +| **Parameter** | **Description** | **Type** | **Required** | **Default** | +|:--------------|:----------------------------------------------------------------------|:---------|:-------------|:------------| +| lat | The latitude of the geographic location | Float | Yes | `undefined` | +| lon | The longitude of the geographic location | Float | Yes | `undefined` | +| alt | The elevation of the geographic location | Integer | No | `null` | +| start | The start date of the query (YYYY-MM-DD) | String | Yes | `undefined` | +| end | The end date of the query (YYYY-MM-DD) | String | Yes | `undefined` | +| model | Substitute missing records with statistically optimized model data | String | No | `true` | +| freq | The time frequency of the records. Can be used for custom aggregation | String | No | `null` | +| units | The unit system of the meteorological parameters | String | No | metric | + +For full specification of available frequencies, defined by the `freq` parameter, please see [here](https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#offset-aliases). + +The `units` parameter takes one of the following values: + +* _metric_ (Celsius, Millimeters, Kilometers per hour) +* _imperial_ (Fahrenheit, Inches, Miles per hour) +* _scientific_ (Kelvin, Millimeters, Meters per second) ## Response -The response body includes the following properties. +The response body includes the following properties. Please note that all units mentioned below refer to the default `units` setting. | **Parameter** | **Description** | **Type** | |:--------------|:------------------------------------------|:---------| -| date | The date string (format: YYYY-MM-DD) | String | +| date | The date string (YYYY-MM-DD) | String | | tavg | The average air temperature in °C | Float | | tmin | The minimum air temperature in °C | Float | | tmax | The maximum air temperature in °C | Float | | prcp | The daily precipitation total in mm | Float | -| snow | The snow depth in mm | Integer | +| snow | The maximum snow depth in mm | Integer | | wdir | The average wind direction in degrees (°) | Integer | | wspd | The average wind speed in km/h | Float | | wpgt | The peak wind gust in km/h | Float | @@ -55,7 +66,10 @@ More information about the data format is available [here](/formats.html). The following example requires the cURL command-line interface. Alternatively, you can use an API client like Postman. ```sh -curl --header "x-api-key: {key}" "https://api.meteostat.net/v2/point/daily?lat=33.749&lon=-84.388&alt=336&start=2019-06-01&end=2019-06-30" +curl --request GET \ + --url 'https://meteostat.p.rapidapi.com/point/daily?lat=43.6667&lon=-79.4&start=2020-01-01&end=2020-01-31&alt=184' \ + --header 'x-rapidapi-host: meteostat.p.rapidapi.com' \ + --header 'x-rapidapi-key: {key}' ``` Please replace `{key}` with your personal API key. diff --git a/src/api/point/hourly.md b/src/api/point/hourly.md index 9922129..46814b2 100644 --- a/src/api/point/hourly.md +++ b/src/api/point/hourly.md @@ -4,52 +4,62 @@ title: Hourly Data | Point Data | JSON API # Hourly Data -This endpoint provides historical hourly observations for a geographic location. Furthermore, gaps in the time series can be filled in with statistically optimized model data. The data provided through this endpoint is aggregated from multiple governmental interfaces. +This endpoint provides historical hourly observations for any geographic location. Furthermore, gaps in the time series can be filled in with statistically optimized model data. The data provided through this endpoint is aggregated from multiple governmental interfaces. Hourly observations are coming in with an offset of about two to three hours. However, some data might be added multiple days or even months later, depending on how the different weather services are updating their datasets. -Hourly data can be queried for a **maximum of 10 days** per request. +Hourly data can be queried for a **maximum of 30 days** per request. ## Endpoint Hourly data is provided through this endpoint: ``` -GET https://api.meteostat.net/v2/point/hourly +GET https://meteostat.p.rapidapi.com/point/hourly ``` ## Parameters -In order to query data for any location you’ll need to specify the `lat` and `lon` parameters. You will probably also want to add the `alt` parameter to your request to make the output more precise. If you do not set the `alt` parameter, Meteostat will detect the elevation using its own elevation model. +In order to query data for any location you’ll need to specify the `lat` and `lon` parameters. You will probably also want to add the `alt` parameter to your request to make the output more precise. If you do not set the `alt` parameter, Meteostat will detect the elevation using nearby weather stations. -| **Parameter** | **Description** | **Type** | **Required** | **Default** | -|:--------------|:-------------------------------------------------|:---------|:-------------|:------------| -| lat | The latitude of the geographic location | Float | Yes | `undefined` | -| lon | The longitude of the geographic location | Float | Yes | `undefined` | -| alt | The elevation of the geographic location | Integer | No | 0 | -| start | The start date of the query (format: YYYY-MM-DD) | String | Yes | `undefined` | -| end | The end date of the query (format: YYYY-MM-DD) | String | Yes | `undefined` | -| tz | The time zone according to the tz database | String | No | UTC | +| **Parameter** | **Description** | **Type** | **Required** | **Default** | +|:--------------|:----------------------------------------------------------------------|:---------|:-------------|:------------| +| lat | The latitude of the geographic location | Float | Yes | `undefined` | +| lon | The longitude of the geographic location | Float | Yes | `undefined` | +| alt | The elevation of the geographic location | Integer | No | `null` | +| start | The start date of the query (YYYY-MM-DD) | String | Yes | `undefined` | +| end | The end date of the query (YYYY-MM-DD) | String | Yes | `undefined` | +| tz | The time zone according to the tz database | String | No | UTC | +| model | Substitute missing records with statistically optimized model data | String | No | `true` | +| freq | The time frequency of the records. Can be used for custom aggregation | String | No | `null` | +| units | The unit system of the meteorological parameters | String | No | metric | + +For full specification of available frequencies, defined by the `freq` parameter, please see [here](https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#offset-aliases). + +The `units` parameter takes one of the following values: + +* _metric_ (Celsius, Millimeters, Kilometers per hour) +* _imperial_ (Fahrenheit, Inches, Miles per hour) +* _scientific_ (Kelvin, Millimeters, Meters per second) ## Response -The response body includes the following properties. - -| **Parameter** | **Description** | **Type** | -|:--------------|:---------------------------------------------------------------------------|:---------| -| time | UTC time stamp (format: YYYY-MM-DD hh:mm:ss) | String | -| time_local | Local time stamp (format: YYYY-MM-DD hh:mm:ss); only provided if tz is set | String | -| temp | The air temperature in °C | Float | -| dwpt | The dew point in °C | Float | -| rhum | The relative humidity in percent (%) | Integer | -| prcp | The one hour precipitation total in mm | Float | -| snow | The snow depth in mm | Integer | -| wdir | The wind direction in degrees (°) | Integer | -| wspd | The average wind speed in km/h | Float | -| wpgt | The peak wind gust in km/h | Float | -| pres | The sea-level air pressure in hPa | Float | -| tsun | The one hour sunshine total in minutes (m) | Integer | -| coco | The weather condition code | Integer | +The response body includes the following properties. Please note that all units mentioned below refer to the default `units` setting. + +| **Parameter** | **Description** | **Type** | +|:--------------|:-------------------------------------------|:---------| +| time | Time (YYYY-MM-DD hh:mm:ss) of observation | String | +| temp | The air temperature in °C | Float | +| dwpt | The dew point in °C | Float | +| rhum | The relative humidity in percent (%) | Integer | +| prcp | The one hour precipitation total in mm | Float | +| snow | The snow depth in mm | Integer | +| wdir | The wind direction in degrees (°) | Integer | +| wspd | The average wind speed in km/h | Float | +| wpgt | The peak wind gust in km/h | Float | +| pres | The sea-level air pressure in hPa | Float | +| tsun | The one hour sunshine total in minutes (m) | Integer | +| coco | The weather condition code | Integer | More information on the data formats and weather condition codes is available [here](/formats.html). @@ -58,7 +68,10 @@ More information on the data formats and weather condition codes is available [h The following example requires the cURL command-line interface. Alternatively, you can use an API client like Postman. ```sh -curl --header "x-api-key: {key}" "https://api.meteostat.net/v2/point/hourly?lat=49.4967&lon=8.4795&alt=104&start=2020-01-01&end=2020-01-01&tz=Europe/Berlin" +curl --request GET \ + --url 'https://meteostat.p.rapidapi.com/point/hourly?lat=43.6667&lon=-79.4&start=2020-01-01&end=2020-01-01&alt=113&tz=America%2FToronto' \ + --header 'x-rapidapi-host: meteostat.p.rapidapi.com' \ + --header 'x-rapidapi-key: {key}' ``` Please replace `{key}` with your personal API key. @@ -70,7 +83,6 @@ The data output returns one object per hour. Have a look at this example: ```json { "time": "2019-12-31 23:00:00", - "time_local": "2020-01-01 00:00:00", "temp": 1.6, "dwpt": 0.1, "rhum": 90, diff --git a/src/api/point/monthly.md b/src/api/point/monthly.md new file mode 100644 index 0000000..080baa1 --- /dev/null +++ b/src/api/point/monthly.md @@ -0,0 +1,93 @@ +--- +title: Monthly Data | Point Data | JSON API +--- + +# Monthly Data + +This endpoint provides historical monthly statistics for any geographic location. The data provided through this endpoint is aggregated from multiple governmental interfaces. + +Monthly data is coming in with an offset of multiple months. Additionally, Meteostat aggregates monthly data from hourly observations, daily records and model data. + +## Endpoint + +Monthly data is provided through this endpoint: + +``` +GET https://meteostat.p.rapidapi.com/point/monthly +``` + +## Parameters + +In order to query data for any location you’ll need to specify the `lat` and `lon` parameters. You will probably also want to add the `alt` parameter to your request to make the output more precise. If you do not set the `alt` parameter, Meteostat will guess the elevation based on nearby weather stations. + +| **Parameter** | **Description** | **Type** | **Required** | **Default** | +|:--------------|:----------------------------------------------------------------------|:---------|:-------------|:------------| +| lat | The latitude of the geographic location | Float | Yes | `undefined` | +| lon | The longitude of the geographic location | Float | Yes | `undefined` | +| alt | The elevation of the geographic location | Integer | No | `null` | +| start | The start date of the query (YYYY-MM-DD) | String | Yes | `undefined` | +| end | The end date of the query (YYYY-MM-DD) | String | Yes | `undefined` | +| model | Substitute missing records with statistically optimized model data | String | No | `true` | +| freq | The time frequency of the records. Can be used for custom aggregation | String | No | `null` | +| units | The unit system of the meteorological parameters | String | No | metric | + +For full specification of available frequencies, defined by the `freq` parameter, please see [here](https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#offset-aliases). + +The `units` parameter takes one of the following values: + +* _metric_ (Celsius, Millimeters, Kilometers per hour) +* _imperial_ (Fahrenheit, Inches, Miles per hour) +* _scientific_ (Kelvin, Millimeters, Meters per second) + +## Response + +The response body includes the following properties. Please note that all units mentioned below refer to the default `units` setting. + +| **Parameter** | **Description** | **Type** | +|:--------------|:------------------------------------------------|:---------| +| date | The first date (YYYY-MM-DD) of the month | String | +| tavg | The average daily air temperature in °C | Float | +| tmin | The average daily minimum air temperature in °C | Float | +| tmax | The average daily maximum air temperature in °C | Float | +| prcp | The monthly precipitation total in mm | Float | +| snow | The maximum snow depth in mm | Integer | +| wdir | The average wind direction in degrees (°) | Integer | +| wspd | The average wind speed in km/h | Float | +| wpgt | The peak wind gust in km/h | Float | +| pres | The average sea-level air pressure in hPa | Float | +| tsun | The monthly sunshine total in minutes (m) | Integer | + +More information about the data format is available [here](/formats.html). + +## Example + +The following example requires the cURL command-line interface. Alternatively, you can use an API client like Postman. + +```sh +curl --request GET \ + --url 'https://meteostat.p.rapidapi.com/point/monthly?lat=52.5244&lon=13.4105&start=2020-01-01&end=2020-12-31&alt=43' \ + --header 'x-rapidapi-host: meteostat.p.rapidapi.com' \ + --header 'x-rapidapi-key: {key}' +``` + +Please replace `{key}` with your personal API key. + +### Data Response + +The data output returns one object per month. Have a look at this example: + +```json +{ + "date": "2020-01-01", + "tavg": 4.1, + "tmin": 1, + "tmax": 7, + "prcp": 37, + "snow": 0, + "wdir": 191.3, + "wspd": 11.2, + "wpgt": 77, + "pres": 1025.2, + "tsun": 3300 +} +``` diff --git a/src/api/point/normals.md b/src/api/point/normals.md new file mode 100644 index 0000000..0ac9551 --- /dev/null +++ b/src/api/point/normals.md @@ -0,0 +1,83 @@ +--- +title: Climate Normals | Point Data | JSON API +--- + +# Climate Normals + +Climate normals are long-term averages of historical weather observations. Usually, these means are calculated over a period of 30 years (“_reference period_“). However, any other time series of sufficient length can be used to calculate climate normals. + +Climate normals represent the typical monthly weather at a given location. The averages can also be used for calculating anomalies of current weather and climate conditions. + +## Endpoint + +Climate normals are provided through this endpoint: + +``` +GET https://meteostat.p.rapidapi.com/point/normals +``` + +## Parameters + +In order to query data for any location you’ll need to specify the `lat` and `lon` parameters. You will probably also want to add the `alt` parameter to your request to make the output more precise. If you do not set the `alt` parameter, Meteostat will detect the elevation using its own elevation model. + +| **Parameter** | **Description** | **Type** | **Required** | **Default** | +|:--------------|:-------------------------------------------------|:---------|:-------------|:------------| +| lat | The latitude of the geographic location | Float | Yes | `undefined` | +| lon | The longitude of the geographic location | Float | Yes | `undefined` | +| alt | The elevation of the geographic location | Integer | No | `null` | +| units | The unit system of the meteorological parameters | String | No | metric | + +The `units` parameter takes one of the following values: + +* _metric_ (Celsius, Millimeters, Kilometers per hour) +* _imperial_ (Fahrenheit, Inches, Miles per hour) +* _scientific_ (Kelvin, Millimeters, Meters per second) + +## Response + +The data array of the response contains twelve objects (one per month) for every period. Each of these objects includes the following properties. Please note that all units mentioned below refer to the default `units` setting. + +| **Parameter** | **Description** | **Type** | +|:--------------|:-------------------------------------------------------|:---------| +| start | The first year (YYYY) of the period (if not specified) | Integer | +| end | The last year (YYYY) of the period (if not specified) | Integer | +| month | The month | Integer | +| tavg | The average daily air temperature in °C | Float | +| tmin | The average daily minimum air temperature in °C | Float | +| tmax | The average daily maximum air temperature in °C | Float | +| prcp | The monthly precipitation total in mm | Float | +| wspd | The average wind speed in km/h | Float | +| pres | The average sea-level air pressure in hPa | Float | +| tsun | The monthly sunshine total in minutes (m) | Integer | + +More information about the data format is available [here](/formats.html). + +## Example + +The following example requires the cURL command-line interface. Alternatively, you can use an API client like Postman. + +```sh +curl --request GET \ + --url 'https://meteostat.p.rapidapi.com/point/normals?lat=59.9127&lon=10.7461&alt=26&start=1961&end=1990' \ + --header 'x-rapidapi-host: meteostat.p.rapidapi.com' \ + --header 'x-rapidapi-key: {key}' +``` + +Please replace `{key}` with your personal API key. + +### Data Response + +The data output returns one object per month. Have a look at this example: + +```json +{ + "month": 1, + "tavg": -3.8, + "tmin": -6.3, + "tmax": -1.3, + "prcp": 50.9, + "wspd": null, + "pres": 1011.3, + "tsun": 2400 +} +``` diff --git a/src/api/stations/README.md b/src/api/stations/README.md index 10fd0f7..0e04f40 100644 --- a/src/api/stations/README.md +++ b/src/api/stations/README.md @@ -6,8 +6,8 @@ title: Weather Stations | JSON API A weather station is a location where meteorological data is measured. Most weather stations available via the Meteostat API are operated by governmental organizations like the National Oceanic and Atmospheric Administration (NOAA). Many of these organizations provide public access to the gathered information. Meteostat uses multiple open data interfaces to collect as much weather and climate data as possible. -Nowadays, most stations run fully automized. However, in contrast to computed model data environmental or technical issues can cause gaps in the data series when relying on observations reported by weather stations. Furthermore, some weather stations may only report a small set of meteorological parameters. Please be aware that some data output might be incomplete. +Nowadays, most stations run fully automized. However, in contrast to computed model data, environmental or technical issues can cause gaps in the data series when relying on observations reported by weather stations. Furthermore, some weather stations may only report a small set of meteorological parameters. Please be aware that some data output might be incomplete. ## Contributing -Meteostat operates an open directory of weather stations. Learn more about how to contribute to this collection in the corresponding [documentation](/contributing/stations.html). +Meteostat operates an open directory of weather stations. Learn more about how to contribute to this collection on [GitHub](https://github.com/meteostat/weather-stations). diff --git a/src/api/stations/climate.md b/src/api/stations/climate.md deleted file mode 100644 index be0eaa8..0000000 --- a/src/api/stations/climate.md +++ /dev/null @@ -1,179 +0,0 @@ ---- -title: Climate Normals | Weather Stations | JSON API ---- - -# Climate Normals - -Climate normals are long-term averages of historical weather observations. Usually, these means are calculated over a period of 30 years (_“reference period“_). However, any other time series of sufficient length can be used to calculate climate normals. - -Climate normals represent the typical monthly weather at a given location. The averages can also be used for calculating anomalies of current weather and climate conditions. - -## Endpoint - -Climate normals are provided through this endpoint: - -``` -GET https://api.meteostat.net/v2/stations/climate -``` - -## Parameters - -Just add the station’s ID through the `station` parameter. Please note that not all weather stations provide climate normals. - -| **Parameter** | **Description** | **Type** | **Required** | **Default** | -|:--------------|:-----------------------|:---------|:-------------|:------------| -| station | The weather station ID | String | Yes | `undefined` | - -## Response - -The data array of the response contains twelve objects, one per month. Each of these objects includes the following properties. - -| **Parameter** | **Description** | **Type** | -|:--------------|:-------------------------------------------|:---------| -| month | The integer number of the month (1 to 12) | Integer | -| tavg | The mean temperature in °C | Float | -| tmin | The average minimum temperature in °C | Float | -| tmax | The average maximum temperature in °C | Float | -| prcp | The average total precipitation in mm | Integer | -| pres | The average sea-level air pressure in hPa | Float | -| tsun | The average sunshine duration in hours (h) | Integer | - -More information about the data format is available [here](/formats.html). - -Additionally, the meta object includes the `start` and `end` year of the climate averages. - -## Example - -The following example requires the cURL command-line interface. Alternatively, you can use an API client like Postman. - -```sh -curl --header "x-api-key: {key}" "https://api.meteostat.net/v2/stations/climate?station=10637" -``` - -Please replace `{key}` with your personal API key. - -## Data Response - -The response should look like that: - -```json -{ - "meta": { - "source": "National Oceanic and Atmospheric Administration, Deutscher Wetterdienst", - "start": 1961, - "end": 1990, - "exec_time": 0.015, - "generated": "2020-06-14 10:15:40" - }, - "data": [ - { - "month": 1, - "tavg": 0.7, - "tmin": null, - "tmax": null, - "prcp": 43.8, - "pres": 1018, - "tsun": 41 - }, - { - "month": 2, - "tavg": 1.8, - "tmin": null, - "tmax": null, - "prcp": 39.8, - "pres": 1017.5, - "tsun": 75 - }, - { - "month": 3, - "tavg": 5.2, - "tmin": null, - "tmax": null, - "prcp": 51.1, - "pres": 1014.9, - "tsun": 116 - }, - { - "month": 4, - "tavg": 9.2, - "tmin": null, - "tmax": null, - "prcp": 51.5, - "pres": 1014.2, - "tsun": 163 - }, - { - "month": 5, - "tavg": 13.7, - "tmin": null, - "tmax": null, - "prcp": 61.3, - "pres": 1014.6, - "tsun": 207 - }, - { - "month": 6, - "tavg": 17.1, - "tmin": null, - "tmax": null, - "prcp": 70.2, - "pres": 1015.6, - "tsun": 209 - }, - { - "month": 7, - "tavg": 18.9, - "tmin": null, - "tmax": null, - "prcp": 63, - "pres": 1016.6, - "tsun": 225 - }, - { - "month": 8, - "tavg": 18.3, - "tmin": null, - "tmax": null, - "prcp": 64.8, - "pres": 1016.1, - "tsun": 204 - }, - { - "month": 9, - "tavg": 14.8, - "tmin": null, - "tmax": null, - "prcp": 48.3, - "pres": 1018.3, - "tsun": 158 - }, - { - "month": 10, - "tavg": 9.8, - "tmin": null, - "tmax": null, - "prcp": 50.5, - "pres": 1017.6, - "tsun": 103 - }, - { - "month": 11, - "tavg": 4.7, - "tmin": null, - "tmax": null, - "prcp": 59.4, - "pres": 1018.3, - "tsun": 48 - }, - { - "month": 12, - "tavg": 1.8, - "tmin": null, - "tmax": null, - "prcp": 54.1, - "pres": 1016.9, - "tsun": 39 - } - ] -} -``` diff --git a/src/api/stations/daily.md b/src/api/stations/daily.md index e3062c6..effd773 100644 --- a/src/api/stations/daily.md +++ b/src/api/stations/daily.md @@ -6,40 +6,51 @@ title: Daily Data | Weather Stations | JSON API This endpoint provides historical daily statistics for a particular weather station. The data provided through this endpoint is aggregated from multiple governmental interfaces. -Daily data is coming in with an offset of about one to seven days. However, some data might be added multiple days or even months later, depending on how the different weather services are updating their datasets. Additionally, Meteostat provides daily aggregates based on hourly observations. +Daily data is coming in with an offset of about one to seven days. However, some data might be added multiple days or even months later, depending on how the different weather services are updating their datasets. Additionally, Meteostat provides daily aggregates based on hourly observations and model data. -Daily data can be queried for a **maximum of 370 days** per request. +Daily data can be queried for a **maximum of 10 years** per request. ## Endpoint Daily data is provided through this endpoint: ``` -GET https://api.meteostat.net/v2/stations/daily +GET https://meteostat.p.rapidapi.com/stations/daily ``` ## Parameters When calling this endpoint please refer to the following parameters. -| **Parameter** | **Description** | **Type** | **Required** | **Default** | -|:--------------|:-------------------------------------------------|:---------|:-------------|:------------| -| station | The weather station ID | String | Yes | `undefined` | -| start | The start date of the query (format: YYYY-MM-DD) | String | Yes | `undefined` | -| end | The end date of the query (format: YYYY-MM-DD) | String | Yes | `undefined` | +| **Parameter** | **Description** | **Type** | **Required** | **Default** | +|:--------------|:----------------------------------------------------------------------|:---------|:-------------|:------------| +| station | The weather station ID | String | Yes | `undefined` | +| start | The start date of the query (YYYY-MM-DD) | String | Yes | `undefined` | +| end | The end date of the query (YYYY-MM-DD) | String | Yes | `undefined` | +| model | Substitute missing records with statistically optimized model data | String | No | `true` | +| freq | The time frequency of the records. Can be used for custom aggregation | String | No | `null` | +| units | The unit system of the meteorological parameters | String | No | metric | + +For full specification of available frequencies, defined by the `freq` parameter, please see [here](https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#offset-aliases). + +The `units` parameter takes one of the following values: + +* _metric_ (Celsius, Millimeters, Kilometers per hour) +* _imperial_ (Fahrenheit, Inches, Miles per hour) +* _scientific_ (Kelvin, Millimeters, Meters per second) ## Response -The response body includes the following properties. +The response body includes the following properties. Please note that all units mentioned below refer to the default `units` setting. | **Parameter** | **Description** | **Type** | |:--------------|:------------------------------------------|:---------| -| date | The date string (format: YYYY-MM-DD) | String | +| date | The date string (YYYY-MM-DD) | String | | tavg | The average air temperature in °C | Float | | tmin | The minimum air temperature in °C | Float | | tmax | The maximum air temperature in °C | Float | | prcp | The daily precipitation total in mm | Float | -| snow | The snow depth in mm | Integer | +| snow | The maximum snow depth in mm | Integer | | wdir | The average wind direction in degrees (°) | Integer | | wspd | The average wind speed in km/h | Float | | wpgt | The peak wind gust in km/h | Float | @@ -53,7 +64,10 @@ More information about the data format is available [here](/formats.html). The following example requires the cURL command-line interface. Alternatively, you can use an API client like Postman. ```sh -curl --header "x-api-key: {key}" "https://api.meteostat.net/v2/stations/daily?station=68816&start=2019-06-01&end=2019-06-30" +curl --request GET \ + --url 'https://meteostat.p.rapidapi.com/stations/daily?station=10637&start=2020-01-01&end=2020-01-31' \ + --header 'x-rapidapi-host: meteostat.p.rapidapi.com' \ + --header 'x-rapidapi-key: {key}' ``` Please replace `{key}` with your personal API key. diff --git a/src/api/stations/hourly.md b/src/api/stations/hourly.md index 2cbaaaf..821f407 100644 --- a/src/api/stations/hourly.md +++ b/src/api/stations/hourly.md @@ -8,47 +8,56 @@ This endpoint provides historical hourly observations for a particular weather s Hourly observations are coming in with an offset of about two to three hours. However, some data might be added multiple days or even months later, depending on how the different weather services are updating their datasets. -Hourly data can be queried for a **maximum of 10 days** per request. +Hourly data can be queried for a **maximum of 30 days** per request. ## Endpoint Hourly data is provided through this endpoint: ``` -GET https://api.meteostat.net/v2/stations/hourly +GET https://meteostat.p.rapidapi.com/stations/hourly ``` ## Parameters When calling this endpoint please refer to the following parameters. -| **Parameter** | **Description** | **Type** | **Required** | **Default** | -|:--------------|:------------------------------------------------------------------------------------------------------------------------------|:---------|:-------------|:------------| -| station | The weather station ID | String | Yes | `undefined` | -| start | The start date of the query (format: YYYY-MM-DD) | String | Yes | `undefined` | -| end | The end date of the query (format: YYYY-MM-DD) | String | Yes | `undefined` | -| tz | The time zone according to the tz database | String | No | UTC | -| model | A boolean parameter that specifies whether missing observations should be substituted with statistically optimized model data | Integer | No | 0 | +| **Parameter** | **Description** | **Type** | **Required** | **Default** | +|:--------------|:----------------------------------------------------------------------|:---------|:-------------|:------------| +| station | The weather station ID | String | Yes | `undefined` | +| start | The start date of the period (YYYY-MM-DD) | String | Yes | `undefined` | +| end | The end date of the period (YYYY-MM-DD) | String | Yes | `undefined` | +| tz | The time zone according to the tz database | String | No | UTC | +| model | Substitute missing records with statistically optimized model data | String | No | `true` | +| freq | The time frequency of the records. Can be used for custom aggregation | String | No | `null` | +| units | The unit system of the meteorological parameters | String | No | metric | + +For full specification of available frequencies, defined by the `freq` parameter, please see [here](https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#offset-aliases). + +The `units` parameter takes one of the following values: + +* _metric_ (Celsius, Millimeters, Kilometers per hour) +* _imperial_ (Fahrenheit, Inches, Miles per hour) +* _scientific_ (Kelvin, Millimeters, Meters per second) ## Response -The response body includes the following properties. - -| **Parameter** | **Description** | **Type** | -|:--------------|:---------------------------------------------------------------------------|:---------| -| time | UTC time stamp (format: YYYY-MM-DD hh:mm:ss) | String | -| time_local | Local time stamp (format: YYYY-MM-DD hh:mm:ss); only provided if tz is set | String | -| temp | The air temperature in °C | Float | -| dwpt | The dew point in °C | Float | -| rhum | The relative humidity in percent (%) | Integer | -| prcp | The one hour precipitation total in mm | Float | -| snow | The snow depth in mm | Integer | -| wdir | The wind direction in degrees (°) | Integer | -| wspd | The average wind speed in km/h | Float | -| wpgt | The peak wind gust in km/h | Float | -| pres | The sea-level air pressure in hPa | Float | -| tsun | The one hour sunshine total in minutes (m) | Integer | -| coco | The weather condition code | Integer | +The response body includes the following properties. Please note that all units mentioned below refer to the default `units` setting. + +| **Parameter** | **Description** | **Type** | +|:--------------|:-------------------------------------------|:---------| +| time | Time of observation (YYYY-MM-DD hh:mm:ss) | String | +| temp | The air temperature in °C | Float | +| dwpt | The dew point in °C | Float | +| rhum | The relative humidity in percent (%) | Integer | +| prcp | The one hour precipitation total in mm | Float | +| snow | The snow depth in mm | Integer | +| wdir | The wind direction in degrees (°) | Integer | +| wspd | The average wind speed in km/h | Float | +| wpgt | The peak wind gust in km/h | Float | +| pres | The sea-level air pressure in hPa | Float | +| tsun | The one hour sunshine total in minutes (m) | Integer | +| coco | The weather condition code | Integer | More information on the data formats and weather condition codes is available [here](/formats.html). @@ -57,7 +66,10 @@ More information on the data formats and weather condition codes is available [h The following example requires the cURL command-line interface. Alternatively, you can use an API client like Postman. ```sh -curl --header "x-api-key: {key}" "https://api.meteostat.net/v2/stations/hourly?station=10637&start=2020-02-01&end=2020-02-04" +curl --request GET \ + --url 'https://meteostat.p.rapidapi.com/stations/hourly?station=10637&start=2020-01-01&end=2020-01-01&tz=Europe%2FBerlin' \ + --header 'x-rapidapi-host: meteostat.p.rapidapi.com' \ + --header 'x-rapidapi-key: {key}' ``` Please replace `{key}` with your personal API key. @@ -69,7 +81,6 @@ The data output returns one object per hour. Have a look at this example: ```json { "time": "2019-12-31 23:00:00", - "time_local": "2020-01-01 00:00:00", "temp": 1.6, "dwpt": 0.1, "rhum": 90, diff --git a/src/api/stations/meta.md b/src/api/stations/meta.md index 538eb4e..92bb498 100644 --- a/src/api/stations/meta.md +++ b/src/api/stations/meta.md @@ -9,7 +9,7 @@ This endpoint provides information which describes a specific weather station. T ## Endpoint ``` -GET https://api.meteostat.net/v2/stations/meta +GET https://meteostat.p.rapidapi.com/stations/meta ``` ## Parameters @@ -26,28 +26,45 @@ You’ll need to specify one of the following parameters. The response body includes the following properties. -| **Parameter** | **Description** | **Type** | -|:--------------|:--------------------------------------------------------------------------|:---------| -| id | The Meteostat ID of the weather station | String | -| name | Object containing the name of the weather stations in different languages | Object | -| country | ISO 3166-1 alpha-2 country code of the weather station | String | -| region | ISO 3166-2 state or region code of the weather station | String | -| national | The national ID of the weather station | String | -| wmo | The WMO ID of the weather station | Integer | -| icao | The ICAO ID of the weather station | String | -| iata | The IATA ID of the weather station | String | -| latitude | The latitude of the weather station | Float | -| longitude | The longitude of the weather station | Float | -| elevation | The elevation of the weather station in meters above sea level | Integer | -| timezone | The time zone of the weather station | String | -| inventory | Object containing the periods of available data for this weather station | Object | +* `id`: Meteostat ID (_String_) +* `name`: Name in different languages (_Object_) +* `country`: ISO 3166-1 alpha-2 country code, e.g. CA for Canada (_String_) +* `region`: ISO 3166-2 state or region code, e.g. TX for Texas (_String_) +* `identifiers`: Identifiers (_Object_) + * `national`: National ID (_String_) + * `wmo`: WMO ID (_String_) + * `icao`: ICAO ID (_String_) +* `location`: Geographic location (_Object_) + * `latitude`: Latitude (_Float_) + * `longitude`: Longitude (_Float_) + * `elevation`: Elevation in meters (_Integer_) +* `timezone`: Time zone (_String_) +* `inventory`: Available data by frequency (_Object_) + * `model`: Hourly model inventory data (_Object_) + * `start`: First day (YYYY-MM-DD) of hourly model data (_String_) + * `end`: Last day (YYYY-MM-DD) of hourly model data (_String_) + * `hourly`: Hourly inventory data (_Object_) + * `start`: First day (YYYY-MM-DD) of hourly data (_String_) + * `end`: Last day (YYYY-MM-DD) of hourly data (_String_) + * `daily`: Daily inventory data (_Object_) + * `start`: First day (YYYY-MM-DD) of daily data (_String_) + * `end`: Last day (YYYY-MM-DD) of daily data (_String_) + * `monthly`: Monthly inventory data (_Object_) + * `start`: First year (YYYY) of monthly data (_String_) + * `end`: Last year (YYYY) of monthly data (_String_) + * `normals`: Climate normals inventory data (_Object_) + * `start`: First year (YYYY) of climate normals data (_Integer_) + * `end`: Last year (YYYY) of climate normals data (_Integer_) ## Example The following example requires the cURL command-line interface. Alternatively, you can use an API client like Postman. ```sh -curl --header "x-api-key: {key}" "https://api.meteostat.net/v2/stations/meta?id=71508" +curl --request GET \ + --url 'https://meteostat.p.rapidapi.com/stations/meta?id=10637' \ + --header 'x-rapidapi-host: meteostat.p.rapidapi.com' \ + --header 'x-rapidapi-key: {key}' ``` Please replace `{key}` with your personal API key. @@ -59,32 +76,49 @@ That’s the expected response: ```json { "meta": { - "exec_time": 0.001, - "generated": "2020-06-02 15:54:27" + "exec_time": 0.003, + "generated": "2021-06-21 18:23:58" }, "data": { - "id": "71508", + "id": "10637", "name": { - "en": "Toronto City" + "de": "Frankfurt Flughafen", + "es": "Aeropuerto de Fráncfort", + "en": "Frankfurt Airport" }, - "country": "CA", - "region": "ON", - "national": null, - "wmo": "71508", - "icao": "CXTO", - "iata": null, - "latitude": 43.6667, - "longitude": -79.4, - "elevation": 113, - "timezone": "America/Toronto", + "country": "DE", + "region": "HE", + "identifier": { + "national": "01420", + "wmo": "10637", + "icao": "EDDF" + }, + "location": { + "latitude": 50.05, + "longitude": 8.6, + "elevation": 111 + }, + "timezone": "Europe/Berlin", "inventory": { + "model": { + "start": "2018-01-28", + "end": "2021-06-29" + }, "hourly": { - "start": "2004-08-03", - "end": "2020-05-31" + "start": "1926-01-01", + "end": "2021-06-20" }, "daily": { - "start": "2002-06-04", - "end": "2020-05-25" + "start": "1934-05-01", + "end": "2021-06-18" + }, + "monthly": { + "start": 1934, + "end": 2021 + }, + "normals": { + "start": 1961, + "end": 2020 } } } diff --git a/src/api/stations/monthly.md b/src/api/stations/monthly.md new file mode 100644 index 0000000..8c9c6cd --- /dev/null +++ b/src/api/stations/monthly.md @@ -0,0 +1,91 @@ +--- +title: Monthly Data | Weather Stations | JSON API +--- + +# Monthly Data + +This endpoint provides historical monthly statistics for a particular weather station. The data provided through this endpoint is aggregated from multiple governmental interfaces. + +Monthly data is coming in with an offset of multiple months. Additionally, Meteostat aggregates monthly data from hourly observations, daily records and model data. + +## Endpoint + +Monthly data is provided through this endpoint: + +``` +GET https://meteostat.p.rapidapi.com/stations/monthly +``` + +## Parameters + +When calling this endpoint please refer to the following parameters. + +| **Parameter** | **Description** | **Type** | **Required** | **Default** | +|:--------------|:----------------------------------------------------------------------|:---------|:-------------|:------------| +| station | The weather station ID | String | Yes | `undefined` | +| start | The start date of the query (YYYY-MM-DD) | String | Yes | `undefined` | +| end | The end date of the query (YYYY-MM-DD) | String | Yes | `undefined` | +| model | Substitute missing records with statistically optimized model data | String | No | `true` | +| freq | The time frequency of the records. Can be used for custom aggregation | String | No | `null` | +| units | The unit system of the meteorological parameters | String | No | metric | + +For full specification of available frequencies, defined by the `freq` parameter, please see [here](https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#offset-aliases). + +The `units` parameter takes one of the following values: + +* _metric_ (Celsius, Millimeters, Kilometers per hour) +* _imperial_ (Fahrenheit, Inches, Miles per hour) +* _scientific_ (Kelvin, Millimeters, Meters per second) + +## Response + +The response body includes the following properties. Please note that all units mentioned below refer to the default `units` setting. + +| **Parameter** | **Description** | **Type** | +|:--------------|:------------------------------------------------|:---------| +| date | The first date (YYYY-MM-DD) of the month | String | +| tavg | The average daily air temperature in °C | Float | +| tmin | The average daily minimum air temperature in °C | Float | +| tmax | The average daily maximum air temperature in °C | Float | +| prcp | The monthly precipitation total in mm | Float | +| snow | The maximum snow depth in mm | Integer | +| wdir | The average wind direction in degrees (°) | Integer | +| wspd | The average wind speed in km/h | Float | +| wpgt | The peak wind gust in km/h | Float | +| pres | The average sea-level air pressure in hPa | Float | +| tsun | The monthly sunshine total in minutes (m) | Integer | + +More information about the data format is available [here](/formats.html). + +## Example + +The following example requires the cURL command-line interface. Alternatively, you can use an API client like Postman. + +```sh +curl --request GET \ + --url 'https://meteostat.p.rapidapi.com/stations/monthly?station=10637&start=2020-01-01&end=2020-12-31' \ + --header 'x-rapidapi-host: meteostat.p.rapidapi.com' \ + --header 'x-rapidapi-key: {key}' +``` + +Please replace `{key}` with your personal API key. + +### Data Response + +The data output returns one object per month. Have a look at this example: + +```json +{ + "date": "2020-01-01", + "tavg": 4.1, + "tmin": 1, + "tmax": 7, + "prcp": 37, + "snow": 0, + "wdir": 191.3, + "wspd": 11.2, + "wpgt": 77, + "pres": 1025.2, + "tsun": 3300 +} +``` diff --git a/src/api/stations/nearby.md b/src/api/stations/nearby.md index 22745bf..697ed43 100644 --- a/src/api/stations/nearby.md +++ b/src/api/stations/nearby.md @@ -4,46 +4,47 @@ title: Nearby | Weather Stations | JSON API # Nearby Weather Stations -The nearby endpoint enables users to find weather stations by geo location. When calling this endpoint make sure to provide valid geographic coordinates (decimal degrees) using the lat (latitude) and lon (longitude) parameters. The limit parameter allows us to specify the maximum number of weather stations returned by this endpoint. +This endpoint enables users to find nearby weather stations by geo location. When calling this endpoint, make sure to provide valid geographic coordinates (decimal degrees) using the `lat` (latitude) and `lon` (longitude) parameters. The `limit` parameter allows us to specify the maximum number of weather stations returned by this endpoint. -By default, the endpoint only returns weather stations which are closer than 100 kilometers to the specified geo location. If you want to limit your query to a certain radius in kilometers, just set the radius parameter to any integer value. +By default, the endpoint only returns weather stations which are closer than 100 kilometers to the specified geo location. If you want to limit your query to a certain radius, just set the `radius` parameter to any integer value. ## Endpoint The endpoint is available through this URL: ``` -GET https://api.meteostat.net/v2/stations/nearby +GET https://meteostat.p.rapidapi.com/stations/nearby ``` ## Parameters -When calling this endpoint please refer to the following parameters. +When calling this endpoint, please refer to the following parameters. -| **Parameter** | **Description** | **Types** | **Required** | **Default** | -|:--------------|:--------------------------------------|:----------|:-------------|:------------| -| lat | The latitude of the location | Float | Yes | `undefined` | -| lon | The longitude of the location | Float | Yes | `undefined` | -| limit | The maximum number of results | Integer | No | 8 | -| radius | The radius of the query in kilometers | Integer | No | 100 | +| **Parameter** | **Description** | **Types** | **Required** | **Default** | +|:--------------|:----------------------------------|:----------|:-------------|:------------| +| lat | The latitude of the location | Float | Yes | `undefined` | +| lon | The longitude of the location | Float | Yes | `undefined` | +| limit | The maximum number of results | Integer | No | 10 | +| radius | The radius of the query in meters | Integer | No | 100000 | ## Response The response body includes the following properties. -| **Parameter** | **Description** | **Type** | -|:--------------|:-----------------------------------------------------------------------------------------------|:---------| -| id | The Meteostat ID of the weather station | String | -| name | Object containing the name of the weather stations in different languages | Object | -| active | A boolean value which is true if the weather station reported data within the previous 90 days | Boolean | -| distance | The distance to the geo location defined in the request | Float | +| **Parameter** | **Description** | **Type** | +|:--------------|:----------------------------------------------------|:---------| +| id | The Meteostat ID of the weather station | String | +| distance | The distance to the provided geo location in meters | Float | ## Example -The following example returns the five closest weather stations to Singapore. It requires the cURL command-line interface. Alternatively, you can use an API client like Postman. +This example requires the cURL command-line interface. Alternatively, you can use an API client like Postman. -``` -curl --header "x-api-key: {key}" "https://api.meteostat.net/v2/stations/nearby?lat=1.28&lon=103.83&limit=3" +```sh +curl --request GET \ + --url 'https://meteostat.p.rapidapi.com/stations/nearby?lat=51.5085&lon=-0.1257' \ + --header 'x-rapidapi-host: meteostat.p.rapidapi.com' \ + --header 'x-rapidapi-key: {key}' ``` Please replace `{key}` with your personal API key. @@ -55,33 +56,49 @@ The response should look like that: ```json { "meta": { - "exec_time": 0.022, - "generated": "2020-06-12 12:24:59" + "exec_time": 0.197, + "generated": "2021-06-23 12:02:41" }, "data": [ { - "id": "48694", - "name": { - "en": "Singapore / Paya Lebar" - }, - "active": true, - "distance": 15.3 + "id": "03779", + "distance": 1104.3 + }, + { + "id": "EGLC0", + "distance": 16804.1 + }, + { + "id": "03672", + "distance": 20652.3 + }, + { + "id": "03772", + "distance": 22624.4 + }, + { + "id": "03781", + "distance": 23370 + }, + { + "id": "EGKB0", + "distance": 24009.3 + }, + { + "id": "EGTI0", + "distance": 27961.2 + }, + { + "id": "03776", + "distance": 40063.6 }, { - "id": "48692", - "name": { - "en": "Singapore / Seletar" - }, - "active": true, - "distance": 18.4 + "id": "03673", + "distance": 43155.8 }, { - "id": "48698", - "name": { - "en": "Singapore / Changi Airport" - }, - "active": true, - "distance": 20.8 + "id": "EGUH0", + "distance": 46423.7 } ] } diff --git a/src/api/stations/normals.md b/src/api/stations/normals.md new file mode 100644 index 0000000..806412c --- /dev/null +++ b/src/api/stations/normals.md @@ -0,0 +1,198 @@ +--- +title: Climate Normals | Weather Stations | JSON API +--- + +# Climate Normals + +Climate normals are long-term averages of historical weather observations. Usually, these means are calculated over a period of 30 years (_“reference period“_). However, any other time series of sufficient length can be used to calculate climate normals. + +Climate normals represent the typical monthly weather at a given location. The averages can also be used for calculating anomalies of current weather and climate conditions. + +## Endpoint + +Climate normals are provided through this endpoint: + +``` +GET https://meteostat.p.rapidapi.com/stations/normals +``` + +## Parameters + +Just add the station’s ID through the `station` parameter. Please note that not all weather stations provide climate normals for all periods. + +| **Parameter** | **Description** | **Type** | **Required** | **Default** | +|:--------------|:-------------------------------------------------|:---------|:-------------|:------------| +| station | The weather station ID | String | Yes | `undefined` | +| start | The start year (YYYY) of the period | String | No | `null` | +| end | The end year (YYYY) of the period | String | No | `null` | +| units | The unit system of the meteorological parameters | String | No | metric | + +The `units` parameter takes one of the following values: + +* _metric_ (Celsius, Millimeters, Kilometers per hour) +* _imperial_ (Fahrenheit, Inches, Miles per hour) +* _scientific_ (Kelvin, Millimeters, Meters per second) + +## Response + +The data array of the response contains twelve objects (one per month) for every period. Each of these objects includes the following properties. Please note that all units mentioned below refer to the default `units` setting. + +| **Parameter** | **Description** | **Type** | +|:--------------|:-------------------------------------------|:---------| +| month | The integer number of the month (1 to 12) | Integer | +| tavg | The mean temperature in °C | Float | +| tmin | The average minimum temperature in °C | Float | +| tmax | The average maximum temperature in °C | Float | +| prcp | The average total precipitation in mm | Integer | +| pres | The average sea-level air pressure in hPa | Float | +| tsun | The average sunshine duration in hours (h) | Integer | + +More information about the data format is available [here](/formats.html). + +## Example + +The following example requires the cURL command-line interface. Alternatively, you can use an API client like Postman. + +```sh +curl --request GET \ + --url 'https://meteostat.p.rapidapi.com/stations/normals?station=10637&start=1961&end=1990' \ + --header 'x-rapidapi-host: meteostat.p.rapidapi.com' \ + --header 'x-rapidapi-key: {key}' +``` + +Please replace `{key}` with your personal API key. + +## Data Response + +The response should look like that: + +```json +{ + "meta": { + "exec_time": 0.885, + "generated": "2021-06-23 12:14:35" + }, + "data": [ + { + "month": 1, + "tavg": 0.5, + "tmin": -2.2, + "tmax": 3.2, + "prcp": 43.8, + "wspd": 12.3, + "pres": 1018, + "tsun": 2454 + }, + { + "month": 2, + "tavg": 1.7, + "tmin": -1.6, + "tmax": 5, + "prcp": 39.8, + "wspd": 11.9, + "pres": 1017.5, + "tsun": 4494 + }, + { + "month": 3, + "tavg": 5.6, + "tmin": 0.9, + "tmax": 10.2, + "prcp": 51.1, + "wspd": 12.9, + "pres": 1014.9, + "tsun": 6984 + }, + { + "month": 4, + "tavg": 9.6, + "tmin": 4.4, + "tmax": 14.7, + "prcp": 51.5, + "wspd": 12.2, + "pres": 1014.2, + "tsun": 9756 + }, + { + "month": 5, + "tavg": 13.8, + "tmin": 8.2, + "tmax": 19.3, + "prcp": 61.3, + "wspd": 11.1, + "pres": 1014.6, + "tsun": 12390 + }, + { + "month": 6, + "tavg": 17, + "tmin": 11.6, + "tmax": 22.5, + "prcp": 70.2, + "wspd": 11.1, + "pres": 1015.6, + "tsun": 12564 + }, + { + "month": 7, + "tavg": 18.8, + "tmin": 13.2, + "tmax": 24.3, + "prcp": 63, + "wspd": 10.9, + "pres": 1016.6, + "tsun": 13470 + }, + { + "month": 8, + "tavg": 18.2, + "tmin": 12.7, + "tmax": 23.7, + "prcp": 64.8, + "wspd": 10.2, + "pres": 1016.1, + "tsun": 12234 + }, + { + "month": 9, + "tavg": 15, + "tmin": 9.7, + "tmax": 20.2, + "prcp": 48.3, + "wspd": 10.2, + "pres": 1018.3, + "tsun": 9450 + }, + { + "month": 10, + "tavg": 9.9, + "tmin": 5.7, + "tmax": 14.1, + "prcp": 50.5, + "wspd": 10.1, + "pres": 1017.6, + "tsun": 6150 + }, + { + "month": 11, + "tavg": 5, + "tmin": 2, + "tmax": 7.9, + "prcp": 59.4, + "wspd": 12, + "pres": 1018.3, + "tsun": 2904 + }, + { + "month": 12, + "tavg": 1.8, + "tmin": -0.7, + "tmax": 4.3, + "prcp": 54.1, + "wspd": 12.4, + "pres": 1016.9, + "tsun": 2310 + } + ] +} +``` diff --git a/src/api/stations/search.md b/src/api/stations/search.md deleted file mode 100644 index 2f3fb85..0000000 --- a/src/api/stations/search.md +++ /dev/null @@ -1,142 +0,0 @@ ---- -title: Search | Weather Stations | JSON API ---- - -# Finding Weather Stations - -Many API endpoints require a weather station indentifier. Most weather stations are identified by their WMO ID. However, some weather stations may not be listed in the WMO index. Therefore, these weather stations are given five-digit IDs containing both numbers and letters. - -## Endpoint - -``` -GET https://api.meteostat.net/v2/stations/search -``` - -## Parameters - -| **Parameter** | **Description** | **Type** | **Required** | **Default** | -|:--------------|:------------------------------|:---------|:-------------|:------------| -| query | The search string | String | Yes | `undefined` | -| limit | The maximum number of results | Integer | No | 8 | - -Alternatively, you can download a [full list](/bulk/stations) of all weather stations available via Meteostat in JSON format. - -## Response - -The response body includes the following properties. - -| **Parameter** | **Description** | **Type** | -|:--------------|:-----------------------------------------------------------------------------------------------|:---------| -| id | The Meteostat ID of the weather station | String | -| name | Object containing the name of the weather stations in different languages | Object | -| country | ISO 3166-1 alpha-2 country code of the weather station | String | -| region | The ISO 3166-2 state or region code of the weather station | String | -| national | The national ID of the weather station | String | -| wmo | The WMO ID of the weather station | Integer | -| icao | The ICAO ID of the weather station | String | -| iata | The IATA ID of the weather station | String | -| latitude | The latitude of the weather station | Float | -| longitude | The longitude of the weather station | Float | -| elevation | The elevation of the weather station in meters above sea level | Integer | -| timezone | The time zone of the weather station | String | -| active | A boolean value which is true if the weather station reported data within the previous 90 days | Boolean | - -## Example: Search results for “vancouver” - -The following example shows search results for the term “vancouver”. It requires the cURL command-line interface. Alternatively, you can use an API client like Postman. - -``` -curl --header "x-api-key: {key}" "https://api.meteostat.net/v2/stations/search?query=vancouver" -``` - -Please replace `{key}` with your personal API key. - -### Data Response - -The request returns four results: - -* Vancouver Airport -* West Vancouver -* Vancouver / Officers Row -* Vancouver - -This is the JSON output: - -```json -{ - "meta": { - "exec_time": 0.022, - "generated": "2020-06-14 10:06:26" - }, - "data": [ - { - "id": "71892", - "name": { - "en": "Vancouver Airport" - }, - "country": "CA", - "region": "BC", - "national": null, - "wmo": "71892", - "icao": "CYVR", - "iata": null, - "latitude": 49.1833, - "longitude": -123.1667, - "elevation": 3, - "timezone": "America/Vancouver", - "active": true - }, - { - "id": "71784", - "name": { - "en": "West Vancouver" - }, - "country": "CA", - "region": "BC", - "national": null, - "wmo": "71784", - "icao": "CWWA", - "iata": null, - "latitude": 49.35, - "longitude": -123.1833, - "elevation": 178, - "timezone": "America/Vancouver", - "active": true - }, - { - "id": "KVUO0", - "name": { - "en": "Vancouver / Officers Row" - }, - "country": "US", - "region": "WA", - "national": null, - "wmo": null, - "icao": "KVUO", - "iata": null, - "latitude": 45.6205, - "longitude": -122.6565, - "elevation": 9, - "timezone": "America/Los_Angeles", - "active": true - }, - { - "id": "71201", - "name": { - "en": "Vancouver" - }, - "country": "CA", - "region": "BC", - "national": null, - "wmo": "71201", - "icao": "CWHC", - "iata": null, - "latitude": 49.3, - "longitude": -123.1167, - "elevation": 2, - "timezone": "America/Vancouver", - "active": true - } - ] -} -``` diff --git a/src/api/wrapper/javascript.md b/src/api/wrapper/javascript.md deleted file mode 100644 index 361518a..0000000 --- a/src/api/wrapper/javascript.md +++ /dev/null @@ -1,152 +0,0 @@ ---- -title: JavaScript | Wrapper | JSON API ---- - -# JavaScript Wrapper - -Meteostat provides a convenient JavaScript wrapper for its JSON API. - -**Table of Contents** - -[[toc]] - -## Installation - -To install the package, run: - -``` -npm install meteostat -``` - -or - -``` -yarn add meteostat -``` - -## Usage - -All you need to get started is an API key, which can be generated [here](https://auth.meteostat.net/). Once you have your personal API key, you can create a client: - -```javascript -import Meteostat from 'meteostat' - -const meteostat = new Meteostat('YOUR_API_KEY_HERE') - -;(async () => { - try { - const { data } = await meteostat.stations.search({ query: 'Sao Paulo' }) - console.log(data) - } catch (error) { - console.log(error) - } -})() -``` - -## Weather Stations - -The methods described in this chapter provide access to meta and weather data of actual weather stations. Alternatively, you can query data by geographical coordinates using [point data](#point-data). - -### Finding Weather Stations - -This method provides access to the data made available through the [_stations/search_](/api/stations/search.html) endpoint. The method takes the same parameters and uses the same response format as the corresponding endpoint. - -```javascript -meteostat.stations.search({ query: 'Sao Paulo' }) -``` - -### Nearby Weather Stations - -This method provides access to the data made available through the [_stations/nearby_](/api/stations/nearby.html) endpoint. The method takes the same parameters and uses the same response format as the corresponding endpoint. - -```javascript -meteostat.stations.nearby({ - lat: -23.5505199, - lon: -46.6333094, -}) -``` - -### Meta Data - -This method provides access to the data made available through the [_stations/meta_](/api/stations/meta.html) endpoint. The method takes the same parameters and uses the same response format as the corresponding endpoint. - -```javascript -meteostat.stations.meta({ - id: '83779', -}) -``` - -### Hourly Data - -This method provides access to the data made available through the [_stations/hourly_](/api/stations/hourly.html) endpoint. The method takes the same parameters and uses the same response format as the corresponding endpoint. - -```javascript -meteostat.stations.hourly({ - station: 83779, - start: '2020-11-12', - end: '2020-11-12', -}) -``` - -### Daily Data - -This method provides access to the data made available through the [_stations/daily_](/api/stations/daily.html) endpoint. The method takes the same parameters and uses the same response format as the corresponding endpoint. - -```javascript -meteostat.stations.daily({ - station: 83779, - start: '2020-11-12', - end: '2020-11-12', -}) -``` - -### Climate Normals - -This method provides access to the data made available through the [_stations/climate_](/api/stations/climate.html) endpoint. The method takes the same parameters and uses the same response format as the corresponding endpoint. - -```javascript -meteostat.stations.climate({ - station: 83779, -}) -``` - -## Point Data - -The methods described in this chapter provide access to meteorological data through geographical coordinates. - -### Hourly Data - -This method provides access to the data made available through the [_point/hourly_](/api/point/hourly.html) endpoint. The method takes the same parameters and uses the same response format as the corresponding endpoint. - -```javascript -meteostat.point.hourly({ - lat: -23.5505199, - lon: -46.6333094, - start: '2020-11-12', - end: '2020-11-12', -}) -``` - -### Daily Data - -This method provides access to the data made available through the [_point/daily_](/api/point/daily.html) endpoint. The method takes the same parameters and uses the same response format as the corresponding endpoint. - -```javascript -meteostat.point.daily({ - lat: -23.5505199, - lon: -46.6333094, - start: '2020-11-12', - end: '2020-11-12', -}) -``` - -### Climate Normals - -This method provides access to the data made available through the [_point/climate_](/api/point/climate.html) endpoint. The method takes the same parameters and uses the same response format as the corresponding endpoint. - -```javascript -meteostat.point.climate({ - lat: -23.5505199, - lon: -46.6333094, -}) -``` diff --git a/src/bulk/stations.md b/src/bulk/stations.md index 55f5110..bd7f10c 100644 --- a/src/bulk/stations.md +++ b/src/bulk/stations.md @@ -49,6 +49,9 @@ Both the lite and the regular dump are equally structured. Each object represent * `monthly`: Monthly inventory data (_Object_) * `start`: First year (YYYY) of monthly data (_String_) * `end`: Last year (YYYY) of monthly data (_String_) + * `normals`: Climate normals inventory data (_Object_) + * `start`: First year (YYYY) of climate normals data (_String_) + * `end`: Last year (YYYY) of climate normals data (_String_) ## Contributing