Solar Web Services API by Meteotest

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/m²	Global radiation on the horizontal plane.
`dh`	W/m²	Diffuse radiation on the horizontal plane
`bh`	W/m²	Direct radiation on the horizontal plane
`gk`	W/m²	Global radiation on the inclined plane
`dni`	W/m²	Direct normal irradiation
`gh_max`	W/m²	Global clear sky radiation
`e`	Wh/kW_p	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/m²	Global radiation on the horizontal plane.
`dh`	W/m²	Diffuse radiation on the horizontal plane
`bh`	W/m²	Direct radiation on the horizontal plane
`gk`	W/m²	Global radiation on the inclined plane
`dni`	W/m²	Direct normal irradiation
`e`	Wh/kW_p	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/m²	Global radiation on the horizontal plane.
`dh`	W/m²	Diffuse radiation on the horizontal plane
`bh`	W/m²	Direct radiation on the horizontal plane
`gk`	W/m²	Global radiation on the inclined plane
`dni`	W/m²	Direct normal irradiation
`e`	Wh/kW_p	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)

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.