Skip to main content

Overview

note

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.

note

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.

NameDescription
BasicCommon weather variables like temperature, precipitation, pictograms
CurrentCurrent temperate and weather condition
Sun & moonInformation about rise and set times for moon and sun
AgroSoil temperature, moisture and evapotranspiration
WindWind gusts and 80 m wind speeds
CloudsLow, mid and high clouds
SeaWave height and speed
SolarShortwave, diffuse, direct normalized and global normalized radiation
PVProSolar photovoltaic forecast
AirCAPE, lifted index, helicity and additional cloud data
Air qualityOzone, particle concentration PM2.5 PM10, SO2, NO2, CO concentration
Trend14 day ensemble forecast
MultimodelForecast from multiple independent weather models
Seasonal3 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:

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 .

ParameterDescriptionExample
latLatitude coordinate in WGS-84&lat=47.5584
lonLongitude 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.

ParameterDescriptionExample
aslElevation 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.

ParameterDescriptionExample
tzTimezone&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
IMPORTANT NOTICE:

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 hour
  • mph: Miles per hour
  • kn: Knots
  • bft: 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 URL
  • YMD: Similar to above, but omits dashes. Example: 20191024 00:00 Example URL
  • iso8601: A standard timestamp 2019-10-24T00:00+02:00 with timezone offset. Example URL
  • timestamp_utc: An integer unix timestamp without an utc-offset. 1571868000 corresponds to 2019-10-23T22:00:00+00:00. The utc offset has to be applied again to get local time. Example URL
  • timestamp_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

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 parametersUnitsDescription
Modelrun updatetimejjjj-mm-dd hh:mmProvides the time of data availability in a UTC timestamp
Modelrun UTCjjjj-mm-dd hh:mmFor single models: Date of model launch, for normal feeds with nowcasting and observations, it provides the same output as the modelrun updatetime
Timezone abbrevationAbbreviation for timezone. Find more information here.
UTC timeoffsethourTime difference between local-time of request and UTC time
NameName of the location of interest
HeightmMeters above sea level
LatitudeDecimal degreesGeographical coordinate system (WGS-84). Latitude measures the distance north or south of the equator, with the equator at 0°. Find more information here.
LongitudeDecimal degreesGeographical 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 timemsCalculation 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", ...]
}
Last updated on