Overview
For product information and Forecast API purchases, please see the Forecast API product page.
This page here and the following subpages contain all technical information about the Forecast API.
For questions regarding the API v2 migration, please check our API v2 FAQ. This page contains all technical information about the new meteoblue API.
We aim to provide a seamless migration process to the new API version. The current API will be replaced with the new API on 2024-03-04 at 10:00 CET.
The meteoblue Forecast API groups weather variables into packages. The basic-1h
package includes a 7 day forecast with hourly values for temperature, wind speed, humidity and precipitation. The package agro-1h
is designed for agronomy and contains evapotranspiration and soil moisture in hourly resolution. The unique design of the Forecast API allows you to combine multiple packages into one HTTP API call.
Weather data can be retrieved by coordinates with latitude and longitude for every place world wide. The following example demonstrates how a basic-1h
and agro-1h
can be called in a HTTP call for Basel, Switzerland at the WGS84 coordinates 47.56°N / 7.57°E
.
http://my.meteoblue.com/packages/basic-1h_agro-1h?lat=47.56&lon=7.57&apikey=DEMOKEY
The API returns weather forecast as JSON:
{
"time": ["2019-10-24 00:00", "2019-10-24 01:00", "2019-10-24 02:00", ...],
"temperature": [12.69, 12.35, 12.09, ...],
"windspeed": [1.80, 1.80, 1.70, ...],
"evapotranspiration": [0.07, 0.14, 0.19, ...],
"wetbulbtemperature": [11.62, 11.27, 11.57, ...]
}
Natively, the time resolution of most weather models is hourly, sometimes 3 hourly. Alongside such hourly or 3 hourly data, which, depending on the variable, either is instant, backwards or summed up, most of the meteoblue data packages can be selected with a variety of aggregations or interpolations. The available aggregations usually are "6h" and "day", and provide minima, maxima, means or sums. The available interpolations usually are "5min", "6min", "10min", "15min", "20min" and "30min", and provide interpolated instant values.
The following example demonstrates how 10 minutes interpolated, hourly and daily data can be requested within one API call:
http://my.meteoblue.com/packages/basic-10min_basic-1h_basic-day?lat=47.56&lon=7.57&apikey=DEMOKEY
The returned JSON consists of 3 sections data_xmin
, data_1h
and data_day
that each contain data for each time interval:
{
"data_xmin": {
"time": ["2019-10-24 00:00", "2019-10-24 00:10"],
"temperature": [12.69, 12.65]
},
"data_1h": {
"time": ["2019-10-24 00:00", "2019-10-24 01:00"],
"temperature": [12.69, 12.35]
},
"data_day": {
"time": ["2019-10-24", "2019-10-25"],
"temperature_max": [17.03, 15.00],
"temperature_min": [11.07, 10.01],
"temperature_mean": [13.73, 12.39]
}
}
The examples above as well as in the following use a special API key &apikey=DEMOKEY
in the URL and are only for demonstration purposes.
Overview of Most Common Packages
Different packages are available for different use-cases. The following table lists the most common packages and a short description. A more detailed view for each package is available later in this document. A table-of-contents is also available on the right hand side.
Name | Description |
---|---|
Basic | Common weather variables like temperature, precipitation, pictograms |
Current | Current temperate and weather condition |
Sun & moon | Information about rise and set times for moon and sun |
Agro | Soil temperature, moisture and evapotranspiration |
Wind | Wind gusts and 80 m wind speeds |
Clouds | Low, mid and high clouds |
Sea | Wave height and speed |
Solar | Shortwave, diffuse, direct normalized and global normalized radiation |
PVPro | Solar photovoltaic forecast |
Air | CAPE, lifted index, helicity and additional cloud data |
Air quality | Ozone, particle concentration PM2.5 PM10, SO2, NO2, CO concentration |
Trend | 14 day ensemble forecast |
Multimodel | Forecast from multiple independent weather models |
Seasonal | 3 months seasonal forecast |
Accounting
Access to the meteoblue API is authenticated with a meteoblue API key. Customers receive a meteoblue API key with a limited number of calls for each package. The API key is a simple URL parameter &apikey=DEMOKEY
.
Every API data package is accounted. We provide detailed statistics on the number of daily calls. For example, if you call basic-day_basic-3h
, each data package is accounted separately: 1 call of basic-day
and 1 call of basic-3h
.
You will be given a maximum number of calls per day, e.g. 1'000 calls to basic-day
and 1'000 calls to basic-3h
. If you exceed your daily quota, an error will occur on the following API calls.
Without further agreement, we impose a rate limit of 500 calls per minute. If you plan to download more than 10'000 data packages, please evenly distribute your calls over a few hours.
API Queries
Every call to the meteoblue API has the following form:
http://my.meteoblue.com/packages/[package-name]-[aggregation]?[parameters]
Mandatory parameters are coordinates latitude and longitude. The following parameters are available and explained in more detail in the following sections:
&lat=47.5584&lon=7.57327
WGS84 coordinates to specify the location&asl=276
Elevation in meters&tz=Europe%2Fzurich
Timezone&format=csv
Select JSON or CSV format&temperature=F
Select Fahrenheit or Celsius&windspeed=ms-1
Different wind speed units&precipitationamount=inch
Different precipitation units&timeformat=Y-M-D
Time stamp format&forecast_days=7
Set number of forecast days&history_days=3
Select number of previous days to include
Mandatory URL Query Parameters
Coordinates
The Forecast API can be requested for one single location. To get the weather forecast for multiple coordinates, you have to perform multiple calls. meteoblue uses regular WGS-84 latitude and longitude coordinates in decimal degrees format (47.56°N / 7.57°E
). Coordinates with arc hours and seconds are not supported.
For the coordinate of Basel, Switzerland 47.56°N / 7.57°E
the URL parameters &lat=47.56&lon=7.57
can be used. South and West is indicated with negative values. The coordinates for Santiago de Chile (33.457°S / 70.648°W) are thus &lat=-33.457&lon=-70.648
.
Parameter | Description | Example |
---|---|---|
lat | Latitude coordinate in WGS-84 | &lat=47.5584 |
lon | Longitude coordinate in WGS-84 | &lon=7.57327 |
Optional URL Query Parameters
Elevation
The elevation in meters above sea level can be specified in the URL with &asl=276
.
If no elevation is supplied, the API will automatically use a digital elevation model (DEM
) with 80 meters resolution to find the correct elevation for the specified coordinates. If the elevation is available, we recommend to add it to the API call.
The elevation is important to perform adjustments to the weather forecast. Especially in complex alpine terrain, the API behaves different for coordinates in a valley and on the mountain. To illustrate the difference, try the following forecasts for Sion a town in a valley of the Swiss alps and observe the drastic change in the forecast if 3500 meter elevation is selected.
Sion is surrounded by high mountains. The meteoblue high resolution weather domains correctly adapt the weather forecast to the terrain. Although the coordinates are the same and only the elevation differs, not only the temperature is adjusted, but also corrections in the clouds, precipitation and winds can be seen.
Parameter | Description | Example |
---|---|---|
asl | Elevation in meters | &asl=279 |
Time Zone
The time zone is important to display data in local-time and aggregate data to daily values. The time zone can be specified with &tz=Europe%2Fzurich
. The characters %2F
represent an URL encoded slash /
. The tz database is used to resolve the time zone names to utc offsets. A list of all available timezones is available here.
If no time zone is available, the API will detect the time zone automatically. For coordinates on sea, the API tries to find a time zone close to shore (approximately up to 50 km), otherwise UTC
is used.
For automated system and further data-processing we highly recommend the use of UTC
without any local time zone offset and daylight saving time. This can be selected with &tz=utc
.
For timezones with daylight saving time, only the time-offset at the time of the API call will be used. There will be no daylight saving time switches in the actual data. So if a place switches from Summertime to Wintertime on Sunday (20.11.2019) and the api is called on Saturday (19.11.2019), all days of the forecasts will use Summertime.
For timezones with fractional offset hours like Delhi, India with Asia/Kolkata +05:30
, the offset will be rounded to a full hour internally.
To set a fixed UTC offset for example 2 hours &tz=GMT-02:00
can be used. This would be equivalent to central European summer time (CEST). Please note that sign is intentionally inverted to follow the specification.
Parameter | Description | Example |
---|---|---|
tz | Timezone | &tz=Europe%2Fzurich |
Output Format
Per default the API returns data formatted as JSON, but other formats are available as well. The CSV format can be selected with &format=csv
.
json
: Recommended format with support for all package combinations. Additional fields might be added without prior notice.csv
: Daily and hourly data cannot be requested in one call. Example for Basel
Please be careful with using CSV. Make sure to always parse the header and check the column location of the queried variable, as these positions might change, when new variables are added and this might happen without any communication from meteoblue.
Weather Variable Units
Different units for temperature, wind speed, wind direction and precipitation can be selected. Per default Celsius, meters per second, degree and millimeter are selected.
For temperature &temperature=C
, Fahrenheit can be selected with &temperature=F
.
For wind speed &windspeed=kmh
, the following options are available:
ms-1
: Meters per second (default)kmh
: Kilometers per hourmph
: Miles per hourkn
: Knotsbft
: Beaufort
For wind direction &winddirection=degree
, 2 direction characters (&winddirection=2char
) or 3 characters (&winddirection=3char
) can be selected. A definition of the wind direction characters can be found here.
For precipitation with default millimeter &precipitationamount=mm
, inch can be selected with &precipitationamount=inch
.
Time Format
Per default the API uses a simple Year-Month-Day Hour:Minute
time format. The time format can be selected with the URL parameter &timeformat=Y-M-D
.
Available time formats:
Y-M-D
: Default.2019-10-24 00:00
Example URLYMD
: Similar to above, but omits dashes. Example:20191024 00:00
Example URLiso8601
: A standard timestamp2019-10-24T00:00+02:00
with timezone offset. Example URLtimestamp_utc
: An integer unix timestamp without an utc-offset.1571868000
corresponds to2019-10-23T22:00:00+00:00
. The utc offset has to be applied again to get local time. Example URLtimestamp_ms_utc
: Same as above, but multiplied with 1000 to get milliseconds. Example URL
Note: If the time format is specified, timestamps always are returned in UTC timezone per default. To get local time, you have to apply the timezone-offset, additionally to the time format.
Forecast Length
The first value will start at 0:00
local-time and offers as many forecast hours as possible. This is typically more than 7 days and might offer even 8 days, depending on the timezone of a given location. If the forecast should be exactly 7 days the &forecast_days=7
parameter can be used. This also allows to limit the maximum forecast length.
Furthermore, the meteoblue API offers up to 4 days of the previous forecasts for all weather variables included in the data packages. To select 4 days of historical data, the url parameter &history_days=4
can be used.
http://my.meteoblue.com/packages/basic-day?lat=47.56&lon=7.57&history_days=3
Note that the historical data, which can be delivered by the forecast API by using the &history_days=
parameter, includes different postprocessing, depending on the amount of days it is in the past already. The following chart displays this in detail:
![Ringbuffer](/assets/images/ringbuffer_2021-08-20-85f4a5911904e191e58d2ef6963120ff.png)
For additional historical data going back over 40 years, we offer the history packages.
Misc
A &name=Basel
parameter can be added. This location name is included in the output JSON, but has otherwise no effect. The location name must be properly URL encoded in case special UTF-8 characters are used. For example the URL encoded representation for Zürich is &name=Z%C3%BCrich
.
API Output
Modelrun
The API output parameter modelrun_utc
displays the initialisation time of the meteoblue model run which delivers the raw meteoblue model data to the forecast API packages, in UTC.
All meteoblue models produce two runs per day, which are initiated at 00:00 AM / PM.
Note: Unless raw model data is collected specifically, for various variables, such as temperature and wind, the delivered API data actually is not raw model data, but a bestfit multimodelmix, which has undergone various postprocessings with measurements and observations. Accordingly, the API is updated up to every 5 minutes, depending on the availability of other forecast models, measurements and observations. This reduces the meaning of the displayed model run.
Modelrun Update Time
The API output parameter modelrun_updatetime_utc
displays the time at which the last meteoblue model run has been completed.
Recommendation: For general use cases, we recommend to update the weather forecast twice per day, starting at 08:00 local time before the start of the working day (optimised for business decisions etc.). For complex decisions you can check the last update times of the available models in the table of the meteoblue multimodel diagram), or in the meteoblue update time API. For high-accuracy usecases, such as in the renewable energy sector, more updates per day (24, or even 96) can be beneficial, depending on the availability of high-frequent measurements or observations.
General output parameters
Output parameters | Units | Description |
---|---|---|
Modelrun updatetime | jjjj-mm-dd hh:mm | Provides the time of data availability in a UTC timestamp |
Modelrun UTC | jjjj-mm-dd hh:mm | For single models: Date of model launch, for normal feeds with nowcasting and observations, it provides the same output as the modelrun updatetime |
Timezone abbrevation | Abbreviation for timezone. Find more information here. | |
UTC timeoffset | hour | Time difference between local-time of request and UTC time |
Name | Name of the location of interest | |
Height | m | Meters above sea level |
Latitude | Decimal degrees | Geographical coordinate system (WGS-84). Latitude measures the distance north or south of the equator, with the equator at 0°. Find more information here. |
Longitude | Decimal degrees | Geographical coordinate system (WGS-84). Longitude measures the distance east or west of the prime meridian, which runs through Greenwich, England, and is at 0°. Find more information here. |
Generation time | ms | Calculation time that was needed for the modelrun |
Package specific output parameters: Please check the specific package content: PV Pro, Wind Power
Example output
For better understanding, a number of example API outputs can be found below. While the specifics differ depending on the package used, the JSON output always comes grouped into three objects:
"metadata" contains the parameters that establish the context for which the call is valid, such as location and time (see table above for details):
"metadata":
{
"name": "Basel",
"latitude": 47.56,
"longitude": 7.57,
"height": 279,
"timezone_abbrevation": "CEST",
"utc_timeoffset": 2.00,
"modelrun_utc": "2019-08-20 00:00",
"modelrun_updatetime_utc": "2019-08-20 07:22"
},
"units" lists all units required to interpret the values provided by the package:
"units":
{
"time": "YYYY-MM-DD hh:mm",
"temperature": "C",
"windspeed": "ms-1"
},
The third object, the name and contents of which depend on the package used, contains the values queried by the call:
Example output: Package "Current"
"data_current":
{
"pictocode": 6,
"time": "2019-08-20 15:05",
"temperature": 14.90,
"isdaylight": 1,
"windspeed": 1.19,
"isobserveddata": 1,
"zenithangle": 40.80,
"pictocode_detailed": 23
},
Example output: Package "Sun and Moon"
"data_day":
{
"time": ["2019-05-14", "2019-05-15", ...],
"sunrise": ["05:52", "05:50", ...],
"sunset": ["20:59", "21:00", ...],
"moonrise": ["15:33", "16:50", ...],
"moonset": ["04:08", "04:35", ...],
"moonphaseangle": [122.50, 135.70, ...],
"moonage": [10.05, 11.13, ...],
"moonphasename": ["waxing gibbous", "waxing gibbous", ...]
},
Example output: Package "Web Colors"
"data_day":
{
"temperature_max_color": ["#FCAC05", "#F88D00", ...],
"temperature_max_fontcolor": ["#000000", "#000000", ...],
"temperature_min_color": ["#B5FF33", "#B5FF33", ...],
"temperature_min_fontcolor": ["#000000", "#000000", ...],
"temperature_mean_color": ["#F8DF0B", "#F8DF0B", ...],
"temperature_mean_fontcolor": ["#000000", "#000000", ...],
"felttemperature_max_color": ["#F88D00", "#FC4F00", ...],
"felttemperature_max_fontcolor": ["#000000", "#000000", ...],
"felttemperature_min_color": ["#D8F7A1", "#D8F7A1", ...],
"felttemperature_min_fontcolor": ["#000000", "#000000", ...],
"predictability_class_color": ["#a0ce00", "#4eb400", ...],
"windspeed_max_color": ["#F8F8F8", "#F8F8F8", ...],
"windspeed_mean_color": ["#F8F8F8", "#F8F8F8", ...],
"windspeed_min_color": ["#F8F8F8", "#F8F8F8", ...]
}