Documentation


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

Introduction

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

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 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
        },
      },
    }
  }
} 

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|php|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 "Solar forecast 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|php|html] Data output format. See output for details.

CloudMove forecasts 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.

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|php|html] Data output format. See output for details.

SolarSat is 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.

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

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)