Child pages
  • Solargis API User Guide

Versions Compared

Key

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

...

The aim of Solargis API is to provide programmatic access to Solargis database and procedures (e.g. PV or GTI calculator) for computers over the web. API is a "user interface" for developers. Developers can automate sending requests and receiving Solargis products by using standard web protocols as FTP or HTTP and smoothly integrate the results (FTP, HTTP) and integrate values into their processing chain (for evaluation. monitoring, forecasting, validation, calibration etc.). 

...


Solargis API endpoint
Available dataTechnical information
Historic dataOperational dataForecast / nowcast dataLong-term average dataWeb protocolCommunicationContent type
FTP API(tick)(tick)(error)FTP

asynchronous

CSV (request and response)
WS API Time Series(tick)(tick)(error)HTTP (SOAP or REST-like)synchronousXML (request and response)
WS API Long-term Averages(error)(error)(error)(tick)HTTP (SOAP or REST-like)synchronousXML (request and response)

...

  • Solargis FTP API - The service can deliver regularly updated PV simulation, solar radiation and meteorological data to remote FTP directories. This service provides the most comprehensive set of input parameters. Request processing is asynchronous (client registers a request, server handles the request later, client then checks for the response) and can be done regularly (e.g. once per day, per month) or occasionally. Both request and response are CSV delimited text files, thus they can easily be automated and processed in batch mode. In case of FTP API for operational data, every single day the user is updated by operational data for yesterday. After the calendar month is fully completed, user is shipped with the same data again, because not all inputs are fully ready at the time of the daily update. This process is called re-analysis. There can be a minor difference between operational and re-analysed (archive or final) data. Available amount of requested data is related to available period of the particular data source. Please refer to the map of coverage. For pricing and setting up FTP user account, please contact us. FTP API can be also used for forecasting.
  • Solargis WS API Time Series - This standard Web service is aimed for quickly serving operational and forecast data (PV simulation, solar radiation and meteorological data) in synchronous manner (client waits for server to finish response). Typical usage for the service is performance monitoring, forecasting, comparisons of recorded vs. simulated PV data, asset management. Due to performance reason the amount of data within one request is currently limited to period of max. 31 days regardless to time resolution (the same rule applies for daily, hourly or 15-minute time step). Both request and response are XML documents.  WS API request parameters (represented as XML elements and attributes) are formally described by XML Schema Definition documents (XSD). By using  XML schema document, each piece of XML document can be verified programmatically. For this service we provide two endpoint variants, classical standard SOAP or more light REST-like access. Look for more technical information hereForecast / nowcast data are available in the same way as with the FTP APIis also available. Authentication and billing is based on API key registered with the user. Please contact us to discuss your specific requirements, and we will prepare a customized quotation for you.
  • Solargis WS API Long-term Averages - Standard XML-based Web service provides long-term averaged PV simulation, solar radiation and meteo. meteorological data with global coverage. Suitable for site prospection and feasibility. The service imitates the click on Calculate button in in interactive Solargis pvPlanner application. The request and response for the service is not covered in this user guide. Technical information can be found here.

 Historical archived data is available in ranges according to regions showed in orange color on the coverage map below. For other regions use climData online shop. 

...

Historical and Operational PV and Solar Radiation Data

Locations within orange regions are capable to be automatically updated (typically daily) in case of FTP API. Periods when data is available for are depicted on the map image above. For the We regularly update locations in orange regions with operational and nowcast data (daily, resp. hourly). For the North, Central and for part of South America data is available as full-time series since 1999 (GOES-EAST satellite data, NOAA). For east China, for Korea, Japan and Australia there are full-time series since July 2007 (MTSAT satellite  and HIMAWARIsatellite data, JMA) available. For south of Africa and Europe (MSG satellite data, EUMETSAT) available period date starts on January 2010. We gradually expands these zones. The same These regions are available for FTP API and  WS API Time Series. For the gray regions areas on the map please use climData online shop. Meteorological data from numerical weather model are available globally within its temporal range (for more information go here). 

...

  • Yellow regions: GFS model from NOAA, USA is available globally with forecasting up to 7 days ahead (today + 7 days = 8 days affected in total). Frequency of the update is once in 12 hours.
  • Violet regions: more advanced IFS model from ECMWF, UK. Frequency of the update is once in 12 hours, forecasting today + 3 days ahead (4 days in total). The rest of days (up to 7 days ahead) is filled covered by GFS model. 

Forecast is based on Solargis post-processing of outputs from numerical weather models. The forecast time series include the following PV, solar radiation and meteorological data parameters in hourly step:

  • Global horizontal irradiance, GHI [W/m2]
  • Global tilted irradiance, GTI [W/m2]
  • Air temperature at 2 m, TEMP [°C]
  • PV electricity output, PVOUT [kWh]

Find more information about forecast here.

Request Parameters

Most detailed comprehensive set of parameters comes with FTP API. Only a subset Subset of the parameters is exposed via WS API Time Series. Following list of parameters is created with regard regards to FTP API (its CSV request). The last column shows the parameter availability in WS API Time Series. There we We use standard XPath notation to describe parameter location within XML request. More information about XML schema used in WS API Time Series can be found here.

...

siteIdlatlngaltsummarizationprocessingKeysactive
MySite148.6125917.65040220hourlyGHI DIF TEMPTRUE

WS API Time Series

There are is no regularly processed request in case of this standard synchronous web service. Instead, the client posts will post the request , waits and wait for the response and handles it. For technicalities visit this link. User Developer can play with test various requests directly from web browser by using e.g. REST Client for Firefox. Set From within REST Client set HTTP Method to "POST", endpoint URL to: https://solargis.info/ws/rest/datadelivery/request?key=demo and also set header "Content-Type: application/xml". Then post the examples below in the body of the request and explore responses. Note, there is a limit of max. 31 days within requested date period. Typically developer will create client code to schedule requests and handle responses. This client code can be created based on XSD schema documents by multiple libraries (JAXB for Java, PyXB for Python etc.)

Data request example

Setting "dateFrom" and "dateTo" is required in all cases. User can control time zone for output data in two ways. Either by using "timeZone" element or by the "dateFrom" and "dateTo" attributes of "dataDeliveryRequest" element. The "timeZone" element takes precedence over "dateFrom" and "dateTo" attributes.

...