Documentation


Solar forecast is a part of our Meteotest Data eXchange API (MDX), which provides a variety of weather related services, both measurements and forecasts.

Introduction

Solar forecast is a part of our Meteotest Data eXchange API (MDX), 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

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 Default Values Comment
site_id Yes - Integer The site ID, see listing sites for values.
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

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 forecast 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.

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. 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)

Forecast 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

Sending real-time measurement data

If you are a customer of "Solar forecast Kalman" (see Products), then you must periodically send measurement data for your sites. In contrast to the other requests, this must be done through the HTTP POST protocol (see wikipedia for details about POST). Accepted data formats are JSON and CSV (comma separated values). See our Code samples for details.

Note that measurement data underlies the same conventions as forecast data. 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 gh-value of 300 W/m² 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.

You can plot uploaded measurements of the last 7 days by calling the following URL (fill in your key and a valid site_id):

https://mdx.meteotest.ch/api_v1?key=YOUR_KEY&service=solarforecast&action=plot_measurements&format=png&site_id=SITE_ID

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)