Child pages
  • Solargis API User Guide

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...


Solargis API
Availability of PV, solar and meteorological dataTechnical features
historicaloperationalreal-time & nowcastNWP forecastlong-term averageprotocoltype of communicationcontent type
DataDelivery Data Delivery Web Service

YES

YESYESYESNOHTTPsynchronousXML
pvPlanner Web ServiceNONONONOYESHTTPsynchronousXML
FTP data deliveryYESYESYESYESNOFTPasynchronousCSV

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 regiondata sincelocal DAY-1 is available at

real-time/nowcasting

original satellite scanning frequency

GOES-E (America)1999-01-0110: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 hour30 minutes
MFG/MSG PRIME (Europe and Africa)2005-01-0103:45 UTC15-min resolution, 0-5 hours ahead, data updated every 30-min (usable via WS), shipping by FTP every 1 hour15 minutes
MTSAT/HIMAWARI (Asia and Pacific)2006-07-0122: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-0122:40 UTC 15-min resolution, 0-5 hours ahead, data updated every 30-min (usable via WS), shipping by FTP every 1 hour30 min. (15 min. since Feb 2017) 
GOES-W (America and Pacific)1999-01-0113:00 UTC (Hawaii)planned30 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 deliveryRequiredValue typeValue unitDefault valueValue RangeDescriptionWS request equivalent (XPath)
siteIdYesstring   Unique identification of one request (one row in CSV request). example: "DETROIT_roof_1"/dataDeliveryRequest/site/@id
fromDateNostring   String formatted as "yyyymmdd" (example "20150101")./dataDeliveryRequest/@dateFrom
toDateNostring   String formatted as "yyyymmdd" (example "20150101")./dataDeliveryRequest/@dateTo
forecastFromDayYes (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
forecastToDayYes (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
summarizationYesstring  
  • MIN_15
  • MIN_30
  • HOURLY
  • DAILY
  • MONTHLY
  • YEARLY
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
processingKeysYesstring  
  • GHI
  • DNI
  • DIF
  • GTI
  • SE
  • SA
  • TEMP
  • AP
  • RH
  • WS
  • WD
  • PVOUT
  • PREC
  • SWE
  • TMOD

The white-space-separated list of variable codes which will be included in the response (example: "GHI DIF TEMP WS WD"):

  • GHI: Global horizontal radiation, (W/m2 for instantaneous values, Wh/m2 for hourly values, kWh/m2  for daily, monthly and yearly values).
  • DNI: Direct normal radiation, (W/m2 for instantaneous values, Wh/m2 for hourly values, kWh/m2  for daily, monthly and yearly values).
  • DIF: Diffuse horizontal radiation, (W/m2 for instantaneous values, Wh/m2 for hourly values, kWh/m2  for daily, monthly and yearly values).
  • GTI: Global tilted radiation, (W/m2 for instantaneous values, Wh/m2 for hourly values, kWh/m2  for daily, monthly and yearly values). Consider setting up the "geometry", "azimuth" and "tilt" parameters, otherwise default will be horizontal surface.
  • SE: Sun altitude (elevation) angle (degrees).
  • SA:  Sun azimuth angle (degrees).
  • TEMP: Air temperature at 2 m (degrees Celsius).
  • AP: Atmospheric pressure (hPa).
  • RH: Relative humidity (%).
  • WS:  Wind speed at 10 m (m/s)
  • WD: Wind direction (degrees), true north-based azimuth. Do not request this variable in time steps above "hourly".
  • PVOUT: Output from PV system (kW for instantaneous, otherwise kWh). Consider setting up "geometry" and related parameters and required PV-related parameters.
  • PREC: Precipitation (rainfall). Unit is kg/m2
  • SWE: Snow Water Equivalent. Daytime values are defined only (nigh time is set  to -99.0). Unit is kg/m2
  • TMOD: PV module temperature (degrees Celsius). The PV configuration has to be defined.
/dataDeliveryRequest/processing/@key
timeZoneNoint 0 (=UTC+0)-12, 12Signed 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\"
timeStampTypeNostring CENTER
  • CENTER
  • END
  • START
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
satelliteTimeStampNostring TRUETRUE or FALSEThis 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. 
terrainShadingNostring FALSETRUE or FALSEApply or not terrain (or horizon) shading (whether default SRTM terrain or local horizon passed by user)./dataDeliveryRequest/processing/@terrainShading
userHorizonNostring   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
activeNostring TRUETRUE or FALSEUser can toggle if the particular request (=site, =row in CSV request file) should be processed or not.N/Alocation should be processed or notN/A

Data Delivery Web Service

XML request

element namedataDeliveryRequest
defined inhttp://solargis.info/schema/ws-data.xsd
descriptionThe 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>. 
contentrequired 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 nameprocessing
defined inhttp://solargis.info/schema/data-request.xsd
descriptionComplex element with instructions about how response should be generated.
contentoptional 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 namesite
defined inhttp://solargis.info/schema/data-request.xsd
descriptionComplex element representing site location, optionally with a PV technology installed
contentoptional 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
@nameoptional, any name of the site, default is empty string


element nameterrain
defined inhttp://solargis.info/schema/data-request.xsd
descriptionGround terrain characterized by altitude, terrain slope and terrain azimuth. This element can affect the self shading of a fixed-angle PV array.
contentnone
@elevationoptional, meters above see level. If missing, the value will be taken from SRTM terrain database
@azimuthoptional, orientation of tilted terrain in degrees, 0 for North, 180 for South, clockwise, default is 180
@tiltoptional, 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

...

summarization