Child pages
  • Solargis API User Guide

Versions Compared

Key

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

...

ParameterRequiredValue typeValue unitDefault valueValue RangeDescriptionpvSpot Web Service equivalent
siteIdYesstring   Unique identification of one request (one row in CSV request). example: "DETROIT_roof_1" 
fromDateYes (for historic data)Nostring   String formatted as "yyyy-mm-dd" (example "2015-01-01"). Date is assumed in UTC. Required Only required when requesting historic historical data by occasionally processed request. For regularly processed requests, avoid of using it (automated process will resolve it). Actual values differ according to data availability, see the coverage map. Moze sa pouzit time zone v CSV? e.g. 2015-02-01-07:00, 2015-02-02ZTime zone can be set directly with the date string, e.g. "2015-02-01-07:00", "2015-02-01+02:00" or "2015-02-02Z" (means UTC or Zulu). Time zone must match a time zone used with "toDate" parameter.
toDateYes (for historic data)Nostring   String formatted as "yyyy-mm-dd" (example "2015-01-01"). Date is assumed in UTC. Only required when requesting historical data by occasionally processed request. For regularly processed requests, avoid of using it (automated process will resolve it). Required when requesting historic data. The value should not exceed the date of TODAY-1 (yesterday), but actual possible value differs according to data availability, see the coverage map. Moze sa pouzit time zone v CSV? e.g. 2015-02-01-07:00, 2015-02-02ZTime zone can be set directly with the date string, e.g. "2015-02-01-07:00", "2015-02-01+02:00" or "2015-02-02Z" (means UTC or Zulu). Time zone must match a time zone used with "fromDate" parameter.
forecastFromDayYes (for forecast data)Nointeger ? is it really required ? 
forecastToDayYes (for forecast data)Nointeger ? is it really required ? 
summarizationYesstring  
  • min10?
  • min15
  • min30
  • hourly
  • daily
  • monthly
  • monthly_longterm
  • 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. 
processingKeysYesstring  
  • GHI
  • DNI
  • DIF
  • GTI
  • SE
  • SA
  • TEMP
  • AP
  • RH
  • WS
  • WD
  • PVOUT

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.
 
timeZoneNostringint GMT+0 (=UTC+0)GMT-12, GMT+ 12String in required format "GMT+/-X". With 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 GMTUTC+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 GMTUTC+0 is used. All the satellite model results are calculated and internally stored in GMTUTC+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 GMTUTC-5 will be read from GMT UTC database as D (5-24 hours) and D+1(0-5 hours). 
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. 
satelliteTimeStampNostring TRUETRUE or FALSEHide this from user .or not ??? 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. 
terrainShadingNostring FALSETRUE or FALSEApply or not terrain (or horizon) shading (whether default SRTM terrain or local horizon passed by user). 
userHorizonNostring   Formatted string describing custom local horizon. Can 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). 
activeNostring TRUETRUE or FALSEUser can toggle if particular request (=site, =row in CSV request file) should be processed or not. 

Request Examples

FTP Data Service

Data request CSV file must have header with parameter names on a first row. Below header, there can be unlimited number of rows with parameter values (site requests). Order of parameters is optional.

Regular data request example

Note, there are no "fromDate" and "toDate" parameters. Date period is resolved according to contract and managed by the automated process.

siteIdlatlngaltgeometryazimuthtiltsummarizationterrainShadingprocessingKeyspvModuleTechnologypvInstallationTypepvInstalledPowerpvInverterEffConstantpvModuleTempNOCTpvModuleTempCoeffPmaxpvLossesDCPollutionSnowpvLossesDCCablespvLossesDCMismatchpvLossesACTransformerpvLossesACCablepvModuleDegradationpvModuleDegradationFirstYeardateStartuppvFieldColumnSpacingRelativepvTrackerBackTrackpvTrackerRotMinpvFieldTerrainSlopepvFieldTerrainAzimuthpvFieldSelfShadingpvFieldTopologyTypeactive
PV_plant_example48.6125920.82707920OneAxisHorizontalNS00hourlyTRUEGHI GTI DIF TEMP PVOUTCSIFREE_STANDING4002098.445-0.453.520.50.90.80.50.8201507012.53TRUE-45,450.545TRUEUNPROPORTIONAL_1TRUE

On-time data request example

Parameters "fromDate" and "toDate" are required in this case. Such request is processed only once. Note, only radiation and temperature is requested here, no PV system settings are needed. 

siteIdlatlngaltgeometryazimuthtiltsummarizationterrainShadingprocessingKeysfromDatetoDateactivetimeZonesatelliteTimeStamptimeStampType
Variant_448.6125920.82707920 FixedOneAngle18020min15FALSEGHI GTI DIF TEMP2012060120121130TRUE0TRUECENTER

Forecast data request example

Note usage of "forecastFromDay" and "forecastToDay" parameters. Typically data will processed each 12 hours with forecasting for today (forecastFromDay=1) up to 7 days ahead (forecastToDay=7).

siteIdlatlnggeometryazimuthtiltsummarizationforecastFromDayforecastToDayterrainShadingprocessingKeyspvModuleTechnologypvInstallationTypepvInstalledPowerpvInverterEffConstantpvModuleTempNOCTpvModuleTempCoeffPmaxpvLossesDCPollutionSnowpvLossesDCCablespvLossesDCMismatchpvLossesACTransformerpvLossesACCablepvModuleDegradationpvModuleDegradationFirstYeardateStartuppvFieldRowSpacingRelativepvFieldColumnSpacingRelativepvTrackerBackTrackpvFieldTerrainSlopepvFieldTerrainAzimuthpvFieldSelfShadingpvFieldTopologyTypeactivepvInverterLimitationACPowertimezonetimestamptype
148.61259117.346977FixedOneAngle031hourly17TRUEGHI GTI TEMP PVOUTCSIFREE_STANDING10097.345-0.453.520.810.50.50.8201505211.731.73FALSE1180TRUEUNPROPORTIONAL_1TRUE300002START

Minimalist PV data request example

Note, degradation is not considered (missing "dateStartup" parameter).

siteIdlatlngaltgeometryazimuthtiltsummarizationprocessingKeyspvModuleTechnologypvInstallationTypepvInstalledPoweractive
PV_plant_example48.6125917.65040220FixedOneAngle1800hourlyGHI GTI DIF TEMP PVOUTCSIFREE_STANDING100TRUE

Minimalist solar data request example

siteIdlatlngaltsummarizationprocessingKeysactive
MySite148.6125917.65040220hourlyGHI DIF TEMPTRUE

pvSpot Web Service

There are no regularly processed request in case of this standard synchronous web service. Instead the client posts the request, waits for response and handles it. For technicalities visit this link.

Data request example

Parameters "fromDate" and "toDate" are required in all cases.

Code Block
<ws:dataDeliveryRequest dateFrom="2014-04-28" dateTo="2014-04-28"
    xmlns="http://geomodel.eu/schema/data/request"
    xmlns:ws="http://geomodel.eu/schema/ws/data"
    xmlns:geo="http://geomodel.eu/schema/common/geo"
    xmlns:pv="http://geomodel.eu/schema/common/pv"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
     
    <site id="site1dummy" name="First site" lat="48.61259" lng="20.827079">
        <geo:terrain elevation="111" azimuth="112" tilt="11"/>
        <geo:horizon>0:5 7.5:3 15:7 22.5:0</geo:horizon>
        <pv:geometry xsi:type="pv:GeometryFixedOneAngle" azimuth="165" tilt="22"/>
        <pv:system installedPower="100" installationType="FREE_STANDING" dateStartup="2011-06-01">
            <pv:module type="CSI">
                <pv:degradation>3</pv:degradation>
                <pv:degradationFirstYear>8</pv:degradationFirstYear>
                <pv:surfaceReflectance>0.13</pv:surfaceReflectance>
                <pv:powerTolerance low="3" high="3"/>
                <pv:nominalOperatingCellTemp>44</pv:nominalOperatingCellTemp>
                <pv:PmaxCoeff>-0.489</pv:PmaxCoeff>
            </pv:module>
            <pv:inverter>
                <pv:efficiency xsi:type="pv:EfficiencyConstant" percent="94"/>
            </pv:inverter>
            <pv:losses>
                <pv:acLosses cables="1" transformer="2.1"/>
                <pv:dcLosses cables="1.2" mismatch="0.65" snowPollution="7" monthlySnowPollution="4 2 3 4 5 7 8 4 7 4 5 1"/>
            </pv:losses>
            <pv:topology xsi:type="pv:TopologySimple" relativeSpacing="2.5"/>
        </pv:system>
    </site>   
    <processing key="GHI DIF DNI PVOUT" summarization="HOURLY" terrainShading="true"/>  
</ws:dataDeliveryRequest>
siteIdlatlngaltgeometryazimuthtiltsummarizationterrainShadingprocessingKeysfromDatetoDateactivetimeZonesatelliteTimeStamptimeStampType
Variant_4-48.998817.65040220 FixedOneAngle18020min15FALSEGHI GTI DIF TEMP2012060120121130TRUE0TRUECENTER

Forecast data request example

Note usage of "forecastFromDay" and "forecastToDay" parameters. Typically data will processed each 12 hours with forecasting for today (forecastFromDay=1) up to 7 days ahead (forecastToDay=7).

siteIdlatlnggeometryazimuthtiltsummarizationforecastFromDayforecastToDayterrainShadingprocessingKeyspvModuleTechnologypvInstallationTypepvInstalledPowerpvInverterEffConstantpvModuleTempNOCTpvModuleTempCoeffPmaxpvLossesDCPollutionSnowpvLossesDCCablespvLossesDCMismatchpvLossesACTransformerpvLossesACCablepvModuleDegradationpvModuleDegradationFirstYeardateStartuppvFieldRowSpacingRelativepvFieldColumnSpacingRelativepvTrackerBackTrackpvFieldTerrainSlopepvFieldTerrainAzimuthpvFieldSelfShadingpvFieldTopologyTypeactivepvInverterLimitationACPowertimezonetimestamptype
1-48.30181117.346977FixedOneAngle031hourly17TRUEGHI GTI TEMP PVOUTCSIFREE_STANDING10097.345-0.453.520.810.50.50.8201505211.731.73FALSE1180TRUEUNPROPORTIONAL_1TRUE300002START

Minimalist PV data request example

Note, degradation is not considered (missing "dateStartup" parameter).

siteIdlatlngaltgeometryazimuthtiltsummarizationprocessingKeyspvModuleTechnologypvInstallationTypepvInstalledPoweractive
PV_plant_example-48.998817.65040220FixedOneAngle1800hourlyGHI GTI DIF TEMP PVOUTCSIFREE_STANDING100TRUE

Minimalist solar data request example

siteIdlatlngaltsummarizationprocessingKeysactive
MySite1-48.998817.65040220hourlyGHI DIF TEMPTRUE


 

Response Examples

FTP Data Service

Responses from this service are standard SolarGIS CSV format files with header, metadata and data sections.They are suitable for automated processing.

pvSpot Web Service