Documentation

The Solar Web Services API is a part of our Weather API, which provides a variety of weather related services, both measurements and forecasts.

Introduction

As a Solar forecast customer, you will obtain a personal API key which allows you to register new photovoltaic sites and request the calculated forecasts for these sites.

First, you have to register a photovoltaic site. This is done by calling the following URL with the required GET parameters: 


https://mdx.meteotest.ch/api_v1?key=YOUR_KEY&service=solarforecast
    &action=siteadd
    &name=My PV site 123
    &latitude=45.1234
    &longitude=13.621
    &azimuth=190
    &inclination=30

Replace YOUR_KEY with your API key (A 32 character combination like AAAABBBBCCCCDDDDEEEEFFFF00001111), and the other parameters according to your site information.

After registering one or more sites, you can request forecast data by calling the following URL: 

https://mdx.meteotest.ch/api_v1?key=YOUR_KEY&service=solarforecast&action=getforecast&format=json

This will return the 72 or 216 hour forecast for all your registered photovoltaic sites, recalculated hourly: 

{
  "statuscode": 200,
  "payload": {
    "solarforecast": {
      "1071": {                    
        "2013-06-17 05:00:00": {
            "tt": 15.8,
            "gh": 58,
            "gk": 70,
            "e": 73
        },
        "2013-06-17 06:00:00": {
            "tt": 17.7,
            "gh": 219,
            "gk": 369,
            "e": 358
        },
        "2013-06-17 07:00:00": {
            "tt": 21.2,
            "gh": 377,
            "gk": 592,
            "e": 543
        },
      },
    }
  }
}

Note that the order of the variables is not fixed in any of the available output formats. Please use the key/value pairs (json/xml) or the header line (csv) to parse the data.

Adding sites

You can register a new site by calling the following URL:

https://mdx.meteotest.ch/api_v1?key=YOUR_KEY&service=solarforecast&action=siteadd
    &name=SITENAME
    &latitude=LAT
    &longitude=LONG
    &azimuth=AZIMUTH
    &inclination=INCLINATION
Parameter Required Default Values Comment
name Yes - URL encoded string Unique identification string of the site. The webservice will assign it a unique ID.
latitude Yes - [+90°, -90°] In decimal format.
longitude Yes - [-180°, 180°] In decimal format.
azimuth 180 [0°, 360°] N: 0°, W: 270°, S: 180°, E: 90°.
inclination 30 [0°, 90°] Inclination of the installed panels. Horizontal: 0°, vertical: 90°.
altitude determined automatically integer Altitude (meters) of the site.
horizon 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 comma separated list of 12 integers > 0 (in degrees) denotes the 360° horizon of the site, in the order north/east/south/west/north. Examples:
  • horizon=20,20,20,0,0,0,0,0,0,0,0,20
    corresponds to a 20° horizon in the north and in the east
  • horizon=0,0,0,0,0,0,0,0,20,20,20,0
    corresponds to a 20° horizon in the west
hddctin - float Heating degree days: Critical inside temperatur in degree celsius [°C].
hddctout - float Heating degree days: Critical outside temperatur in degree celsius [°C].
cddctout - float Cooling degree days: Critical outside temperatur in degree celsius [°C].

Note that — in most cases — the altitude of a site is determined automatically. However, in some regions of the earth automatic determination may fail. In this case you'll see a message telling you to provide the altitude manually. You may also want to provide an explicit altitude if your site is not located at ground level.

Remark: The system does not prevent you from registering multiple sites with identical parameters. However, response data contains a warning message if a a site with identical parameters (i.e., with identical values for latitude, longitude, azimuth, inclination, and altitude) already exists. If you registered identical sites on purpose, you can safely ignore this warning: 

{
  "statuscode": 200,
  "error": null, 
  "payload": {
    "warning": "One or several sites with identical parameters already exist(s) (site IDs: 123, 124)",
    "site": {
    "id": 3341, 
    "altitude": 2199, 
    }
  },
}

Editing Sites

You can update an existing sites information by calling the following URL: 

https://mdx.meteotest.ch/api_v1?key=YOUR_KEY&service=solarforecast&action=siteedit
    &site_id=SITEID
    &name=SITENAME
    &latitude=LAT
    &longitude=LONG
    &azimuth=AZIMUTH
    &inclination=INCLINATION
Parameter Required Values Comment
site_id Yes Integer The site ID, see listing sites for values.
latitude [+90°, -90°] In decimal format.
longitude [-180°, 180°] In decimal format.
azimuth [0°, 360°] N: 0°, W: 270°, S: 180°, E: 90°.
inclination [0°, 90°] Inclination of the installed panels. Horizontal: 0°, vertical: 90°.
altitude integer Altitude (meters) of the site.
horizon comma separated list of 12 integers > 0 (in degrees) denotes the 360° horizon of the site, in the order north/east/south/west/north. Examples:
  • horizon=20,20,20,0,0,0,0,0,0,0,0,20
    corresponds to a 20° horizon in the north and in the east
  • horizon=0,0,0,0,0,0,0,0,20,20,20,0
    corresponds to a 20° horizon in the west
hddctin float Heating degree days: Critical inside temperatur in degree celsius [°C].
hddctout float Heating degree days: Critical outside temperatur in degree celsius [°C].
cddctout float Cooling degree days: Critical outside temperatur in degree celsius [°C].

Deleting sites

You can delete an existing sites by calling the following URL: 

https://mdx.meteotest.ch/api_v1?key=YOUR_KEY&service=solarforecast&action=sitedelete&site_id=SITEID
Parameter Required Default Values Comment
site_id Yes - Integer The site ID, see listing sites for values.

Listing sites

To obtain a list of all your registered sites, call the following URL: 

https://mdx.meteotest.ch/api_v1?key=YOUR_KEY&service=solarforecast&action=siteinfo&format=json

Getting SolarForecast data

To obtain the calculated forecast data for all — or just one, cf. parameter 'site_id' — your registered sites, call the following URL: 

https://mdx.meteotest.ch/api_v1?key=YOUR_KEY&service=solarforecast&action=getforecast&site_id=SITE_ID&format=FORMAT
Parameter Required Default Values Comment
site_id - Integer If this parameter is provided, you'll get a forecast for one site only. If it is omitted, you'll get a forecast for all your registered sites.
format html [json|xml|yaml|csv|html] Data output format. See output for details.

SolarForecasts are recalculated on an hourly basis.

Note that date/time values mark the end of a time interval and forecast values represent the arithmetic mean over that interval. For example, a gh-forecast of 300 W/m2 at 2014-06-17 11:00:00 (UTC) means that 300 is the average global radiation in the interval 2014-06-17 10:00:00 - 2014-06-17 11:00:00. (Note that "SolarForecast Advanced" also allows to define time intervals of 10, 15, 20, or 30 minutes)

SolarForecast Output

Parameter Unit Comment
tt ° C Air Temperature
gh W/m2 Global radiation on the horizontal plane.
dh W/m2 Diffuse radiation on the horizontal plane
bh W/m2 Direct radiation on the horizontal plane
gk W/m2 Global radiation on the inclined plane
dni W/m2 Direct normal irradiation
e Wh/kWp Energy output

Additional meteo parameters

Parameter Unit Comment
rr mm Precipitation
rh % Relative humidity
ff km/h Wind speed
dd Degree Wind direction
fx km/h Wind gust
qff hPa mean sea level pressure
tcc octa total cloud coverage
hdd °C heating degree days
cdd °C cooling degree days
sy [1-16] weather symbol

Getting CloudMove data

To obtain the calculated CloudMove data for all — or just one, cf. parameter 'site_id' — your registered sites, call the following URL: 

https://mdx.meteotest.ch/api_v1?key=YOUR_KEY&service=solarforecast&action=getforecast_cloudmove&site_id=SITE_ID&format=FORMAT
Parameter Required Default Values Comment
site_id - Integer If this parameter is provided, you'll get a forecast for one site only. If it is omitted, you'll get a forecast for all your registered sites.
format html [json|xml|yaml|csv|html] Data output format. See output for details.

CloudMove forecasts are recalculated on a quarter-hourly basis.

Note that date/time values mark the end of a time interval and forecast values represent the arithmetic mean over that interval.

CloudMove Output

Parameter Unit Comment
tt ° C Air Temperature
gh W/m2 Global radiation on the horizontal plane.
dh W/m2 Diffuse radiation on the horizontal plane
bh W/m2 Direct radiation on the horizontal plane
gk W/m2 Global radiation on the inclined plane
dni W/m2 Direct normal irradiation
e Wh/kWp Energy output

Getting SolarSat data

To obtain the calculated SolarSat data for all — or just one, cf. parameter 'site_id' — your registered sites, call the following URL: 

https://mdx.meteotest.ch/api_v1?key=YOUR_KEY&service=solarforecast&action=getsolarsat&site_id=SITE_ID&format=FORMAT
Parameter Required Default Values Comment
site_id - Integer If this parameter is provided, you'll get a forecast for one site only. If it is omitted, you'll get a forecast for all your registered sites.
format html [json|xml|yaml|csv|html] Data output format. See output for details.

SolarSat is recalculated on a quarter-hourly basis.

Note that date/time values mark the end of a time interval and forecast values represent the arithmetic mean over that interval.

SolarSat Output

Parameter Unit Comment
tt ° C Air Temperature
gh W/m2 Global radiation on the horizontal plane.
dh W/m2 Diffuse radiation on the horizontal plane
bh W/m2 Direct radiation on the horizontal plane
gk W/m2 Global radiation on the inclined plane
dni W/m2 Direct normal irradiation
e Wh/kWp Energy output

Uploading Measurement Data

Uploading measurements requires a subscription to the CloudMove «Booster» option.

If your sites provide measurements of global radiation, you can upload them in near real-time (with a maximum delay of 10 minutes, data uploaded too late will not have any effect) by sending POST requests to 

https://mdx.meteotest.ch/api_v1

The body of the POST request must follow the following form: 

key=YOUR_KEY&service=solarforecast&action=add_measurements&format=json
&measurements=JSON_DATA

, where JSON_DATA must follow the following format (replace SITE-ID with the identification number of the corresponding site): 

{
     SITE-ID: {
         "2021-06-11 05:00:00": {
             "gh": 58
         },
         "2021-06-11 05:15:00": {
             "gh": 219
         },
         "2021-06-11 05:30:00": {
             "gh": 369
         },
         ...
     },
     SITE-ID: {
         ...
Example with curl: 
curl --request POST --data 'key=YOUR_KEY
    &service=solarforecast&action=add_measurements&format=json
    &measurements={SITE-ID: {"2021-06-11 05:00:00": {"gh": 58}, ...}' \
    https://mdx.meteotest.ch/api_v1

«Booster» requires time series with 15-minute averages (as in the above example). Uploading time series with temporal spacing finer than 15-minutely is possible, it will not provide any additional value, however (will be resampled to 15-minute averages).

Measurement data underlies the same conventions as forecast data. In particular, make sure to respect units. Also make sure that date/time values are in UTC and mark the end of an interval. Also make sure that measurement values represent the arithmetic mean over a time interval. For example, a 15-minute average value of 58 W/m² for gh at 2021-06-11 05:00:00 (UTC) represents the average global radiation in the interval 2021-06-11 04:45:00 - 2021-06-11 05:00:00.

Encoding, Timezones & Errors

Data encoding is UTF-8.

Time values are in UTC.

Errors are reported within the responses as well as in the HTTP headers using HTTP status codes:

  • 200 is ok
  • 4xx is a client side problem (Invalid key or parameters)
  • 5xx is a server problem (Try again later)