Weather Forecast
Forecast Variables
Parameters have changed.
(copy this URL into your application).
Fetch Historical Data
Hourly Weather Variables
Daily Weather Variables
Parameters have changed.
(copy this
URL into your application).
Historical Weather Data API Documentation
Endpoint
GET /v1/historical
Description
This API endpoint retrieves historical weather data for a specified location and time range. Users can request daily and hourly weather variables, specify units, and choose the output format.
Query Parameters
| Parameter | Type | Required | Description | Possible Values | Default Value |
|---|---|---|---|---|---|
| format | String | No | Format of the response data. | 'csv', 'xlsx', 'json' | 'json' |
| latitude | Float | Yes | Latitude of the location.(Geographical WGS84 coordinates of the location) | -35 to 40 (Africa region) | 6.471 |
| longitude | Float | Yes | Longitude of the location.(Geographical WGS84 coordinates of the location) | -180 to 180 | 3.6356 |
| daily | String | No | Comma-separated list of daily variables to retrieve. | See Daily Variables | air_temperature_min |
| hourly | String | No | Comma-separated list of hourly variables to retrieve. | See Hourly Variables | air_temperature |
| start_date | String | Yes | Start date in 'YYYY-MM-DD' format. | Valid date | 1990-01-01 |
| end_date | String | Yes | End date in 'YYYY-MM-DD' format. | Valid date | 1990-01-10 |
| temperature_unit | String | No | Unit for temperature variables. | 'C', 'F', 'K' | 'K' |
| pressure_unit | String | No | Unit for pressure variables. | 'hPa', 'mmHg' | 'hPa' |
| wind_speed_unit | String | No | Unit for wind speed variables. | 'm/s', 'km/h', 'knot' | 'm/s' |
| precipitation_unit | String | No | Unit for precipitation variables. | 'mm' | 'mm' |
| API key | String | Yes | Api Key to make requests. |
Hourly Variables
| Variable Name | Description | Default Unit |
|---|---|---|
| air_temperature | Air temperature | K |
| wind_speed_10m | Wind speed at 10 meters | m/s |
| wind_speed_100m | Wind speed at 100 meters | m/s |
| soil_temperature_l1 | Soil temperature at level 1 | K |
| soil_temperature_l2 | Soil temperature at level 2 | K |
| soil_temperature_l3 | Soil temperature at level 3 | K |
| soil_temperature_l4 | Soil temperature at level 4 | K |
| 2m_dewpoint_temperature | Dew point temperature at 2 meters | K |
| 10m_instantaneous_wind_gusts | Instantaneous wind gusts at 10 meters | m/s |
Daily Variables
| Variable Name | Description | Default Unit |
|---|---|---|
| air_temperature_min | Minimum air temperature | K |
| air_temperature_max | Maximum air temperature | K |
| wind_speed_10m | Wind speed at 10 meters | m/s |
| soil_temperature_l1 | Soil temperature at level 1 | K |
| soil_temperature_l2 | Soil temperature at level 2 | K |
| soil_temperature_l3 | Soil temperature at level 3 | K |
| soil_temperature_l4 | Soil temperature at level 4 | K |
| surface_net_solar | Surface net solar radiation | J m-2 |
| surface_net_thermal | Surface net thermal radiation | J m-2 |
| top_net_solar | Top net solar radiation | J m-2 |
| evaporation | Total evaporation | m |
| potential_evaporation | Potential evaporation | m |
| top_net_thermal | Top net thermal radiation | J m-2 |
| sensible_heat_flux | Sensible heat flux | J m-2 |
| relative_humidity_min | Minimum relative humidity | % |
| relative_humidity_max | Maximum relative humidity | % |
| surface_pressure | Surface pressure | hpa |
| wind_speed_100m | Wind speed at 100 meters | m/s |
| 2m_dewpoint_temperature | Dew point temperature at 2 meters | K |
| low_cloud_cover | Low cloud cover | 0-1 |
| medium_cloud_cover | Medium cloud cover | 0-1 |
| high_cloud_cover | High cloud cover | 0-1 |
| total_cloud_cover | Total cloud cover | 0-1 |
| total_column_cloud_liquid_water | Total column cloud liquid water | kg m-2 |
| runoff | Total runoff | m |
| subsurface_runoff | Subsurface runoff | m |
| surface_runoff | Surface runoff | m |
| convective_rain_rate | Convective rain rate | kg m-2 s-1 |
| total_column_rain_water | Total column rain water | kg m-2 |
| total_precipitation | Total precipitation | mm |
| 10m_instantaneous_wind_gusts | Instantaneous wind gusts at 10 meters | m/s |
Notes
- The API currently supports locations within Africa and its islands. Latitude must be between -35 and 40.
- You can request only a maximum of two years at a time for hourly variables
- You can request multiple variables by providing a comma-separated list in the 'daily' or 'hourly' parameters.
- If both 'daily' and 'hourly' parameters are omitted, no data will be returned. At least one of 'daily' or 'hourly' must be specified.
- The default response format is JSON. To download data in 'csv' or 'xlsx' format, specify the 'format' parameter accordingly.
- Date format must be 'YYYY-MM-DD'.
- Ensure that the 'start_date' is before the 'end_date'.
Example Request
Retrieve daily maximum and minimum air temperature data for Lagos, Nigeria, from January 1, 2020, to January 7, 2020.
GET /v1/historical?latitude=6.5244&longitude=3.3792&start_date=2020-01-01&end_date=2020-01-07&daily=air_temperature_min,air_temperature_max&temperature_unit=C
Example Response
The response will be a JSON object containing the requested data:
{
"daily": {
"dates": ["2020-01-01", "2020-01-02", "..."],
"air_temperature_min": [22.5, 23.0, "..."],
"air_temperature_max": [30.1, 31.4, "..."]
},
"units": {
"temperature": "C"
},
"latitude": "6.5244",
"longitude": "3.3792"
}
Download Data in CSV Format
To download the data in CSV format, include the 'format' parameter:
GET /v1/historical?latitude=6.5244&longitude=3.3792&start_date=2020-01-01&end_date=2020-01-07&daily=air_temperature_min,air_temperature_max&temperature_unit=C&format=csv
Error Handling
If an error occurs, the API will return a JSON object with an 'error' field set to 'true' and a 'reason' field describing the error.
{
"error": "true",
"reason": "Parameter 'latitude' and 'longitude' must be provided."
}
Contact
If you have any questions or need assistance, please contact the API support team.