Skip to end of metadata
Go to start of metadata

We have implemented REST endpoints for our services. Try our soapUI demos for both SOAP and REST endpoints: ws-demo-soapui-project.xml
Docs to be updated soon

PvPlanner Web Service

click here for sample request and response

DataDelivery Web Service

click here for sample request and response

Simple Usage API

click for details

Implementing client for Web services

Java client implementation guide (full guide here)

  • Define Spring WebServiceTemplate context:

    <?xml version="1.0" encoding="UTF-8"?>
    <beans xmlns="http://www.springframework.org/schema/beans"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:oxm="http://www.springframework.org/schema/oxm"
        xmlns:p="http://www.springframework.org/schema/p"
        xsi:schemaLocation="http://www.springframework.org/schema/oxm http://www.springframework.org/schema/oxm/spring-oxm.xsd
            http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd">
    
      <!-- contextPath - package where to find request and response classes to marshall / unmarshal
           if request and response are in different packages, declare marshaller and unmarshaller separately -->
      <oxm:jaxb2-marshaller id="jaxb2marshaller" contextPath="eu.geomodel.schema.ws.pvplanner"/>
    
      <bean id="pvPlannerTemplate" class="org.springframework.ws.client.core.WebServiceTemplate"
          p:marshaller-ref="jaxb2marshaller" p:unmarshaller-ref="jaxb2marshaller"
          p:defaultUri="https://solargis.info/ws/soap/pvPlanner"> <!-- web service endpoint uri -->
        <property name="interceptors">
          <list>
            <bean class="org.springframework.ws.soap.security.wss4j.Wss4jSecurityInterceptor"
                p:securementActions="Timestamp UsernameToken"
                p:securementUsername="demo"
                p:securementPassword="demo"/>
          </list>
        </property>
      </bean>
    </beans>
    
  • Define client Spring bean:

    // imports omitted
    public class PvPlannerWsClient {
    
      @Autowired
      @Qualifier("pvPlannerTemplate")
      WebServiceTemplate template;
    
      public CalculateResponse callPvPlanner(/*some args*/) {
        return (CalculateResponse) template.marshalSendAndReceive(prepareRequest(/*some args*/));
      }
    
      private CalclulateRequest prepareRequest(/*some args*/) {
        // just sample request
        CalculateRequest request = new CalculateRequest();
        Location location = new Location();
        location.setLat(48.612590); // location of demo site
        location.setLng(20.827079);
        request.setLocation(location);
        PvSystem system = new PvSystem();
        system.setInstalledPower(1);
        system.setModuleType(ModuleTypeEnum.C_SI);
        Settings settings = new Settings();
        settings.setInverterEfficiency(97.5);
        settings.setDcLosses(5.5);
        settings.setAcLosses(1.5);
        settings.setAvailability(99);
        system.setSettings(settings);
        MountingFixedRoofMounted mounting = new MountingFixedRoofMounted();
        mounting.setAzimuth(175);
        mounting.setInclination(45D);
        system.setMounting(mounting);
        request.setSystem(system);
        return request;
      }
    
    }
    

Simple PHP client

We will use request as static XML string. In real environment the request will be generated dynamically.

We wil do a simple curl call to access web service in REST mode.

<?php
header('Content-type: text/xml');
$xml = '<ws:dataDeliveryRequest dateFrom="2014-01-01" dateTo="2014-01-30"
    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 installationType="FREE_STANDING" dateStartup="2011-06-01" availability="99">
            <pv:module type="ASI" count="10" nominalPower="560">
                <pv:degradation>3</pv:degradation>
                <pv:degradationFirstYear>8</pv:degradationFirstYear>
                <pv:surfaceReflectance>0.13</pv:surfaceReflectance>
                <pv:powerTolerance low="10" high="90"/>
                <pv:nominalOperatingCellTemp>15</pv:nominalOperatingCellTemp>
                <pv:openCircuitVoltageCoeff>7</pv:openCircuitVoltageCoeff>
                <pv:shortCircuitCurrentCoeff>4</pv:shortCircuitCurrentCoeff>
                <pv:PmaxCoeff>10</pv:PmaxCoeff>
            </pv:module>
            <pv:inverter count="2" interconnection="PARALLEL">
                <pv:efficiency xsi:type="pv:EfficiencyConstant" percent="94"/>
                <pv:startPower>10</pv:startPower>
                <pv:limitationACPower>5</pv:limitationACPower>
                <pv:nominalDCPower>8</pv:nominalDCPower>
            </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" type="PROPORTIONAL" relativeSpacing="1.5"/>
        </pv:system>
    </site>     
    <processing key="GHI DIF DNI PVOUT" summarization="HOURLY" terrainShading="true"/>     
</ws:dataDeliveryRequest>';
$url = 'https://solargis.info/ws/rest/datadelivery/request?key=demo';
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: text/xml'));
curl_setopt($ch, CURLOPT_POSTFIELDS, $xml);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
 
$response = curl_exec($ch);
curl_close($ch);
echo $response;
?>

Simple Python client

Data delivery web service (WS API for time series)

1. Download this file of sample XML request: datadelivery_demo_request.xml

Content of datadelivery_demo_request.xml file
<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="demo_site" name="Demo site" lat="48.61259" lng="20.827079">
        <geo:terrain elevation="246" azimuth="176" tilt="3.1"/>
        <pv:geometry xsi:type="pv:GeometryFixedOneAngle" azimuth="180" tilt="30"/>
        <pv:system installedPower="10" installationType="FREE_STANDING" dateStartup="2013-10-10">
            <pv:module type="CSI">
                <pv:degradation>0.5</pv:degradation>
                <pv:degradationFirstYear>0.8</pv:degradationFirstYear>
                <pv:nominalOperatingCellTemp>43</pv:nominalOperatingCellTemp>
                <pv:PmaxCoeff>-0.469</pv:PmaxCoeff>
            </pv:module>
            <pv:inverter>
                <pv:efficiency xsi:type="pv:EfficiencyConstant" percent="95"/>
            </pv:inverter>
            <pv:losses>
                <pv:acLosses cables="1" transformer="1"/>
                <pv:dcLosses cables="1" mismatch="1" snowPollution="2.5"/>
            </pv:losses>
        </pv:system>
    </site>
    <processing key="GHI DIF DNI GTI TEMP WS RH PVOUT" summarization="HOURLY" terrainShading="true">
   <timeZone>GMT+02</timeZone>
    </processing>
</ws:dataDeliveryRequest>

2. Open your text editor and create python module named datadelivery_ws_client.py with this content:

import urllib2

if __name__ == '__main__':
   request_xml = open('datadelivery_demo_request.xml').read()
   # alternatively, you obtain request_xml by marshalling from python object
   # print 'Request:', request_xml
   api_key = 'demo'
   url = 'https://solargis.info/ws/rest/datadelivery/request?key=%s' % api_key
   try:
      req = urllib2.Request(url)
      req.add_header('Content-Type', 'application/xml')
      response = urllib2.urlopen(req, request_xml)  # HTTP POST
      response_xml = response.read()
      response_xml = response_xml.replace('&#xD;', '')
      print 'Response:'
      print response_xml
   except urllib2.HTTPError as e:
      print 'Error message from the server: %s' % e.read()
   # parse response_xml and use data (alternatively, first unmarshall the response_xml back to python object)

3. Save the file datadelivery_ws_client.py and run it in your console:

 python datadelivery_ws_client.py

In real production environment you will automatically modify XML request in runtime (e.g. changing location, period etc.). You can do this by using of XML request templates when only particular data will by replaced (e.g. lat, lng, name, dateFrom). In such case the python native The ElementTree XML API can be helpful for XML manipulation. Creating new requests from scratch can be easier by using some "XML data binding" technology. First you generate python objects from Solargis XSD schema documents. Then you can use the python objects for marshalling (serializing python objects into XML text) and unmarshalling (deserializing XML text into python objects) either for the request or response. The PyXB package can be used (http://pyxb.sourceforge.net/).

pvPlanner web service

1. Download this file of sample XML request: pvplanner_demo_request.xml

Content of pvplanner_demo_request.xml file
<calculateRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:geo="http://geomodel.eu/schema/common/geo"
      xmlns:pv="http://geomodel.eu/schema/common/pv"
      xmlns="http://geomodel.eu/schema/ws/pvplanner">
    <site lat="48.612590" lng="20.827079">
        <!-- optional terrain data -->
        <geo:terrain elevation="246" azimuth="176" tilt="3.1" />
        <!-- optional horizon data overriding natural horizon -->
        <!--<geo:horizon>11.11:18.0 7.5:15.53 15.0:10.94 22.5:10.59 30.0:13.06 37.5:14.47 45.0:14.47 52.5:13.76 60.0:12.35 67.5:11.29 75.0:8.12 82.5:4.59 90.0:1.41 97.5:0.35 105.0:0.35 112.5:0.35 120.0:0.35 127.5:0.35 135.0:0.0 142.5:0.0 150.0:0.35 157.5:1.41 165.0:2.47 172.5:2.47 180.0:2.82 187.5:3.18 195.0:2.82 202.5:2.47 210.0:2.47 217.5:2.47 225.0:3.18 232.5:3.18 240.0:2.47 247.5:2.12 255.0:2.12 262.5:2.82 270.0:3.88 277.5:6.71 285.0:8.47 292.5:10.24 300.0:11.29 307.5:12.71 315.0:14.12 322.5:15.53 330.0:16.24 337.5:16.94 345.0:17.29 352.5:17.29</geo:horizon>-->
        <pv:geometry xsi:type="pv:GeometryFixedOneAngle" azimuth="175" tilt="45"/>
        <pv:system installedPower="1" installationType="ROOF_MOUNTED" availability="99">
            <pv:module type="CSI">
            </pv:module>
            <pv:inverter>
                <pv:efficiency xsi:type="pv:EfficiencyConstant" percent="97.5"/>
            </pv:inverter>
            <pv:losses dc="5.5" ac="1.5"/>
        </pv:system>
    </site>
</calculateRequest>

2. Open your text editor and create python module named pvplanner_ws_client.py with this content:

import urllib2

if __name__ == '__main__':
   request_xml = open('pvplanner_demo_request.xml').read()
   # alternatively, you obtain request_xml by marshalling from python object
   # print 'Request:', request_xml
   api_key = 'demo'
   url = 'https://solargis.info/ws/rest/pvplanner/calculate?key=%s' % api_key
   try:
      req = urllib2.Request(url)
      req.add_header('Content-Type', 'application/xml')
      response = urllib2.urlopen(req, request_xml)  # HTTP POST
      response_xml = response.read()
      response_xml = response_xml.replace('&#xD;', '')
      print 'Response:'
      print response_xml
   except urllib2.HTTPError as e:
      print 'Error message from the server: %s' % e.read()
   # parse response_xml and use data (alternatively, first unmarshall the response_xml back to python object)

3. Save the file pvplanner_ws_client.py and run it in your console:

 python pvplanner_ws_client.py

Testing Web services

Demo account

Demo account for testing and Web Services evaluation.

URL key=demo

SOAP WS credentials:

username: demo
password: demo

Access is limited to PvPlanner DEMO microregion (10x10 km): http://solargis.info/pvplanner/#c=48.61259,20.827079&z=11

Testing in web browser

Here is a simple guide how to test the service in browser online: Testing Web Services using browser

soapUI demo

For quick testing and evaluating of our Web Services just import the soapUI demo project ws-demo-soapui-project.xml and submit prepared request messages.
The demo project contains preconfigured #Demo account thus the location is limited to demo region (10x10km).

To use demo account, fill in the following request properties in soapUI:

Security notes

SSL connection certificate

Production WS endpoint (https://solargis.info/ws) is secured by a certificate signed by globally trusted certification authority DigiCert - more info here

No additional configuration is needed, because DigiCert root certificates are trusted by default in most environments.

Web Services Security

WS request is validated against WS-Security standard UsernameToken with password digest and nonce and Timestamp element.

Example SOAP message header with security token:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
  <soapenv:Header>
    <wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" soapenv:mustUnderstand="1">
      <wsse:UsernameToken xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" wsu:Id="UsernameToken-2"
          xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
        <wsse:Username>demo</wsse:Username>
        <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordDigest">Kpr8NgKlQI4wE7Ayo9jm0Z2+hIA=</wsse:Password>
        <wsse:Nonce EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary">g9t2BO4uHOUQoFH5ugQIng==</wsse:Nonce>
        <wsu:Created>2011-06-21T11:37:38.771Z</wsu:Created>
      </wsse:UsernameToken>
      <wsu:Timestamp xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" wsu:Id="Timestamp-1">
        <wsu:Created>2011-06-21T11:37:38.755Z</wsu:Created>
        <wsu:Expires>2011-06-21T11:42:38.755Z</wsu:Expires>
      </wsu:Timestamp>
    </wsse:Security>
  </soapenv:Header>
  <soapenv:Body>
   <!-- Request Message -->
  </soapenv:Body>
</soapenv:Envelope>

Namespaces

Be careful to define all needed namespaces for request message

Write a comment…