...
Solargis API | Availability of PV, solar and meteorological data | Technical features | ||||||
| historical | operational | real-time & nowcast | NWP forecast | long-term average | protocol | type of communication | content type | |
|---|---|---|---|---|---|---|---|---|
| DataDelivery Data Delivery Web Service | YES | YES | YES | YES | NO | HTTP | synchronous | XML |
| pvPlanner Web Service | NO | NO | NO | NO | YES | HTTP | synchronous | XML |
| FTP data delivery | YES | YES | YES | YES | NO | FTP | asynchronous | CSV |
Solargis API consists of two different endpoints:
- DataDelivery Data Delivery Web Service (WS) - the main service for accessing Solargis time series data. Both request and response are XML documents. The request parameters (XML elements and attributes) are formally described by XML Schema Definition documents (XSD). By using the schema, request or response can be verified programmatically. For this service we provide two architectural styles, the REST-like endpoint and SOAP endpoint. Look for more technical information here. Authentication and billing is based on API key registered with the user. Please contact us to discuss details, set up trial or ask for a quotation.
- pvPlanner Web Service - this simple web service provides monthly long-term averaged data (including yearly value) of PV, solar and meteorological data with global coverage. The service is targeted for prospection and prefeasibility. Sending an XML request mimics the click on Calculate button in the interactive Solargis pvPlanner application. Request and response for the service is not described in this user guide. More information can be found here.
...
Schema below shows how the data sources are integrated on an example of the the WS response the Data Delivery Web Service response having 9 days of data (generated at 12:00 of a given day).
...
The following table will help users to schedule time for sending requests to DataDelivery WSData Delivery Web Service:
| satellite region | data since | local DAY-1 is available at | real-time/nowcasting | original satellite scanning frequency |
| GOES-E (America) | 1999-01-01 | 10:00 UTC (USA), 13:00 UTC (whole region) | 15-min resolution, 0-5 hours ahead, data updated every 30-min (usable via WS), shipping by FTP every 1 hour | 30 minutes |
| MFG/MSG PRIME (Europe and Africa) | 2005-01-01 | 03:45 UTC | 15-min resolution, 0-5 hours ahead, data updated every 30-min (usable via WS), shipping by FTP every 1 hour | 15 minutes |
| MTSAT/HIMAWARI (Asia and Pacific) | 2006-07-01 | 22:40 UTC | 10-min resolution, 0-5 hours ahead, data updated every 30-min (usable via WS), shipping by FTP every 1 hour | 30 min. (10 min. since Jan 2016) |
| MFG/MSG IODC (Middle East, Central and South Asia) | 1999-01-01 | 22:40 UTC | 15-min resolution, 0-5 hours ahead, data updated every 30-min (usable via WS), shipping by FTP every 1 hour | 30 min. (15 min. since Feb 2017) |
| GOES-W (America and Pacific) | 1999-01-01 | 13:00 UTC (Hawaii) | planned | 30 minutes |
...
Most comprehensive set of parameters comes with FTP data delivery. Subset of the parameters is exposed via Web Services. Following list of parameters is created with regards to FTP data delivery (CSV request). The last column shows the parameter availability in the WS. The XPath notation is used to describe parameter location within XML request. More information about XML schema used in the WS the Data Delivery Web Service can be found here.
Location and Solar Resource Related Parameters
...
| Parameter name in FTP data delivery | Required | Value type | Value unit | Default value | Value Range | Description | WS request equivalent (XPath) | ||
|---|---|---|---|---|---|---|---|---|---|
| siteId | Yes | string | Unique identification of one request (one row in CSV request). example: "DETROIT_roof_1" | /dataDeliveryRequest/site/@id | |||||
| fromDate | No | string | String formatted as "yyyymmdd" (example "20150101"). | /dataDeliveryRequest/@dateFrom | |||||
| toDate | No | string | String formatted as "yyyymmdd" (example "20150101"). | /dataDeliveryRequest/@dateTo | |||||
| forecastFromDay | Yes (if forecast is needed) | integer | For forecast request only. In case of FTP data delivery, forecast processing is indicated by file name of the CSV request file. Then this parameter is taken into account. 0= DAY+0, 1=DAY+1, etc. | N/A | |||||
| forecastToDay | Yes (if forecast is needed) | integer | For forecast request only. In case of FTP data delivery, forecast processing is indicated by file name of the CSV request file. Then this parameter is taken into account. 1= DAY+1, 2=DAY+2, etc. up to 10. | N/A | |||||
| summarization | Yes | string |
| This parameter defines time resolution of output data. Original satellite and meteorological data are in various time steps (e.g. MSG satellite: 15 min, GOES-EAST satellite: 30 min, GFS weather model: 3 hour). When finer summarization is requested, the data will be interpolated into desired time step. In other words, you can request time resolution of 10 minutes even if the original dataset is not available in such resolution. The "monthly-longterm" summarization means 12 long-term monthly averaged entries + 1 annual entry i the response. | /dataDeliveryRequest/processing/@summarization | ||||
| processingKeys | Yes | string |
| The white-space-separated list of variable codes which will be included in the response (example: "GHI DIF TEMP WS WD"):
| /dataDeliveryRequest/processing/@key | ||||
| timeZone | No | int | 0 (=UTC+0) | -12, 12 | Signed integer. Time zone with hourly precision. Value defines the time zone of output data and it is used for all summarizations. For daily and monthly summarization, the time zone it is activated automatically in the background. This is important for summarization of whole days, otherwise daily summary in UTC+0 would for Japan or Hawaii end up in putting together data from two different local days. For hourly and shorter time steps time zone must be specified, otherwise UTC+0 is used. All the satellite model results are calculated and internally stored in UTC+0. Therefore depending on the requested time zone value, the data reader automatically extends period from which data are read to acquire completed local day. For example, one whole day D (0-24h) in the time zone of UTC-5 will be read from UTC database as D (5-24 hours) and D+1(0-5 hours). | /dataDeliveryRequest/processing/timeZone, timeZone must be in format \"GMT+hh\" or \"GMT-hh\" | |||
| timeStampType | No | string | CENTER |
| The parameter can be used in hourly or even in sub-hourly time steps when averaging of more values occurred within time interval. Example: let's say the value is the result of averaging of more occurrences within hourly interval from 15:00 to 16:00. If the value of the parameter is "CENTER", the value is time-stamped at 15:30, in case of "END" at 16:00 and finally "START" at 15:00. | /dataDeliveryRequest/processing/timeStampType, value START is not supported in Web services | |||
| satelliteTimeStamp | No | string | TRUE | TRUE or FALSE | This parameter is used to preserve time stamp of satellite data acquisition. The data for given position are recorded by satellite in exact moment given by scanning speed of the instrument. For example MSG data scan starts nearby south pole at time T and data for Europe are recorded with 10-13 minutes delay from nominal (start) scan time. To present the original satellite information and avoid degradation of the information content by temporal interpolation it is good to preserve local time stamp of satellite data acquisition. | ||||
| terrainShading | No | string | FALSE | TRUE or FALSE | Apply or not terrain (or horizon) shading (whether default SRTM terrain or local horizon passed by user). | /dataDeliveryRequest/processing/@terrainShading | |||
| userHorizon | No | string | Formatted string describing custom local horizon. The horizon can be in any resolution, it will be interpolated internally. Example (sun azimuth:sun elevation pairs): 0:16.2,0.5:16.2,1:16,1.5:16,2:16,2.5:16,3:15.8,...358.5:16,359:16.2. Azimuth is true north-based (North=0 degree). | /dataDeliveryRequest/site/horizon | |||||
| active | No | string | TRUE | TRUE or FALSE | User can toggle if the particular request (=site, =row in CSV request file) should be processed or not. | N/A | location should be processed or not | N/A |
Data Delivery Web Service
XML request
| element name | dataDeliveryRequest |
|---|---|
| defined in | http://solargis.info/schema/ws-data.xsd |
| description | The root element of the XML request is the <dataDeliveryRequest> with the required attributes 'dateFrom' and 'dateTo' for setting required data period in the response. Accepted is the date string in the form of ''YYYY-mm-dd" e.g., "2017-09-30". It is assumed UTC+0 time zone for both dates unless otherwise specified by the <timeZone> element of the <processing>. |
| content | required one <site> , required one <processing> |
| @dateFrom* | start of the data period |
| @dateTo* | end of the data period |
Explanation of the table above: The element name is that what you can see in the XML request. If the element is of simple type, the content is a literal (text or number), otherwise the content can be list of another <element> or none. Attribute of the element is prefixed by '@' character. Required attribute is marked by '*' character.
| element name | processing |
|---|---|
| defined in | http://solargis.info/schema/data-request.xsd |
| description | Complex element with instructions about how response should be generated. |
| content | optional one <geometry>, optional one <system>, optional one <terrain>, optional one <horizon> |
| @summarization* | required, time frequency in the response. One of YEARLY, MONTHLY, DAILY, HOURLY, MIN_30, MIN_15, MIN_10, MIN_5 |
| @key* | required, list of output data parameters. See below for all supported parameters. |
| @* | required, site longitude in decimal degrees e.g, 20.827079 |
| @ | optional, any name of the site, default is empty string |
| element name | site |
|---|---|
| defined in | http://solargis.info/schema/data-request.xsd |
| description | Complex element representing site location, optionally with a PV technology installed |
| content | optional one <geometry>, optional one <system>, optional one <terrain>, optional one <horizon> |
| @id* | required, site identification, cannot start with number, cannot have white space |
| @lat* | required, site latitude in decimal degrees e.g, 48.61259 |
| @lng* | required, site longitude in decimal degrees e.g, 20.827079 |
| @name | optional, any name of the site, default is empty string |
| element name | terrain |
|---|---|
| defined in | http://solargis.info/schema/data-request.xsd |
| description | Ground terrain characterized by altitude, terrain slope and terrain azimuth. This element can affect the self shading of a fixed-angle PV array. |
| content | none |
| @elevation | optional, meters above see level. If missing, the value will be taken from SRTM terrain database |
| @azimuth | optional, orientation of tilted terrain in degrees, 0 for North, 180 for South, clockwise, default is 180 |
| @tilt | optional, slope tilt of terrain in degrees, 0 for flat ground, 90 for vertical surface, default is 0 (flat) |
To be continued...
Request Examples
FTP data delivery
...
- hourly time-series: Solargis_TS_hourly_sample.csv,
- monthly time-series: Solargis_TS_monthly_sample.csv,
- monthly long-term averages: SolarGIS_LTA_monthly_sample.csv
summarization