 | |
|  |
|
This documentation is meant to provide developers and researchers with an overview of the SWERA Web Service. The web service provides access to the data available in the SWERA spatial database through a point based query. This documentation will provide a description of inputs, outputs, and errors of the SWERA Web Service.
The data sets are categorized as Renewable Energy or Climate. The data are further divided into similar groups of data categories such as DNI, LTI, Temperature, Humidity, etc. For more details on our data structure please see “About Our Data” section below.
The web service allows you to query the SWERA spatial database and get the data returned according to many parameters including: groups, resolutions, annual values, monthly values, and/or individual layers.
Other options will allow you to request data in different output formats, as well as some additional styling information. All of these queries are required for a single latitude/longitude point.
An interactive form has been created in order to help assist with the learning of the SWERA Web Service and its input parameters. The SWERA Interactive Form allows the user to create URL’s in a website page. As the web service parameters are selected on the page, the URL will be updated to allow the user to see how to construct different queries for the web service. Click on the button below to go directly to the interactive form. |
|
|
| |
| |
|
| |
|
This base web service URL, as shown below in bold, is the beginning of the URL needed to access the SWERA Web Service. If this URL is used without parameters, an interactive web service form will be displayed. If additional parameters are used, the SWERA Web Service will accept the user's request, query the database, and return the appropriate data according to those parameters. The URL shown below is the base URL with all the default values.
http://na.unep.net/swera_ims/WS/index.php?coords=0,0&attributes=all&options=basic&format=xml&highestresolution=off&layers=all
The above sample query to the web service is requesting data for all the attributes of all the layers with no extra styling information and all resolutions at the point 0,0. The response will be returned in xml format.
|
|
- Online Documentation
Read the provided documentation to understand the request parameters and XML response fields of the SWERA Web Service.
- Visit the Interactive Web Service Form
This form will allow you to interactively build requests to the web service. As the different parameters are turned on, the web service URL is built at the top of the interactive form.
- Integrate and Utilize the Web Service
Once you understand the SWERA Web Service, integrate the web service into your own applications or websites.
|
|
The SWERA spatial database contains the spatial data created during the SWERA project by each of the partners. These data sets have been categorized into 2 major groups: Renewable Energy and Climate. The Climate category contains the Temperature, Humidity, Pressure as well as Degree Day groups, while the Renewable Energy category holds the DNI, GHI, LTI, and Wind categories. A tree structure representation for each of the categories is shown below.
The table below shows each Renewable Energy layer name along with the name that the Web Service requires. Make sure to use the appropriate Web Service name in your requests to the Web Service.
| Direct Normal Irradiance | dni |
| Global Horizontal Irradiance | ghi |
| Lattitude Tilt Irradiance | tilt |
| Wind | wind |
| DNI DLR High | dni_dlr_high |
| DNI SUNY High | dni_suny_high |
| DNI INPE Mod | dni_inpe_mod |
| DNI NREL Mod | dni_nrel_mod |
| DNI NASA Low | dni_nasa_low |
| GHI DLR High | ghi_dlr_high |
| GHI SUNY High | ghi_suny_high |
| GHI INPE Mod | ghi_inpe_mod |
| GHI NREL Mod | ghi_nrel_mod |
| GNI NASA Low | ghi_nasa_low |
| TILT SUNY High | tilt_suny_high |
| TILT NREL Mod | tilt_nrel_mod |
| TILT INPE Mod | tilt_inpe_mod |
| TILT NASA Low | tilt_nasa_low |
| Wind RISO High | wind_riso_high |
| Wind INPE High | wind_inpe_high |
| Wind NREL High | wind_nrel_high |
| Wind INPE Mod | wind_inpe_mod |
| Wind NASA Low | wind_nasa_low |
The table below shows each Climate layer name along with the name that the Web Service requires. Make sure to use the appropriate Web Service name in your requests to the Web Service.
| Temperature | temp |
| Degree Days | dd |
| Humidity | hum |
| Pressure | pres |
| Air Temperature | clim_temp_nasa_low |
| Earth Skin Temperature | clim_tskin_nasa_low |
| Heating Degree Days | clim_hdd18_nasa_low |
| Cooling Degree Days | clim_cdd10_nasa_low |
| Relative Humidity | clim_rh10m_nasa_low |
| Atmospheric Pressure | clim_ps_nasa_low |
| |
The below parameters can be used to query the SWERA Web Service.
| coords | Required. Single latitude/longitude point to request the data for that location |
| attributes | Optional. Type of values to be returned (annual,monthly,monthlyrange,all). Monthlyrange contains both the monthly values along with the mins nad maxs for each month. Default is all. |
| options | Optional. Determines the amount of information requested (basic,advanced). The advanced option returns everything that the basic option does but with addtional styling information such as the line style for graphing the layer, the color of the line used to graph, etc. Default is basic. |
| layers | Optional. Determines which layers will be shown. You can use all, the groups names (DNI, GHI, LTI,...), resolution levels (high,medium,low), and/or the individual layer names (dni_nasa_low, ghi_suny_high,...). Default is all.
See the section About Our Data for the actual layer names to be used in the layer request. |
| format | Optional. Determines the format (XML,CSV,HOMER) of the response. Default is XML. |
| highestresolution | Optional. If turned on, only one layer per group with the highest resolution will be returned for the coordinates given. This parameter can only be used with “all” layers or specific groups of layers. Default is off. |
|
|
The SWERA Web Service will respond with an XML document containing the below tags
| Data | This element is the root element for the xml. |
| Coords | Contains the latitude and longitude coordinate that was requested. All returned data are for this point. |
| Category | A high level grouping element. |
| CategoryName | The name of the category (Renewable Energy or Climage). |
| CategoryResIndex | An index used for display priority on the SWERA website. |
| Group | A grouping element for the layers. |
| GroupLongTitle | The long title for the group. |
| GroupOrder | An index used for display priority on the SWERA website. |
| Layer | A grouping element for all data associated with the layer. |
| LayerLongTitle | The long title for the layer. |
| LayerShortTitle | The short title for the layer. |
| LayerResIndex | An index used for display priority on the SWERA website.. |
| WiebulK | The Wiebul K value for the wind data (only used for wind layers). Note: -9999 denotes no data |
| GraphLineColor | The color used for graphing the layer in RREX. |
| GraphLineWidth | The line width used for graphing the layer in RREX. |
| LayerHyperlink | The sponsor's hyperlink where you can get more information about the layer and its provider. |
| AnnualMean | The annual mean for the layer. Note: -9999 denotes no data |
| Units | The units for the annual mean. |
| AnnualSpeed | The annual speed of wind layers (only used for wind layers). Note: -9999 denotes no data |
| SpeedUnits | The units for annual speed (only used for wind layers). |
| MonthlyUnits | The units for all the monthly data. |
| Jan,Feb,Mar,... | The data values for the months. Note: -9999 denotes no data |
| JanMin,FebMin,MarMin,... | The minimum data value for the months. Note: -9999 denotes no data |
| JanMax,FebMax,MarMax,... | The maximum data value for the months. Note: -9999 denotes no data |
|
|
The below request is an example of a request to the SWERA Web Service where all the options of the data including styling information is being requested. The SWERA Web Service will retrieve all the attributes of the data, including the monthly, monthlyrange, and annual values, for the GHI and WIND groups only. The highest resolution from each of those two groups will only be requested.
http://na.unep.net/swera_ims/WS/index.php?coords=42.983240,45.000000&attributes=all&options=Advanced&format=XML&highestresolution=On&layers=GHI,WIND
|
|
This is the information you would receive back from the above web service request example.
<Data>
<Coords>42.983240,45.000000</Coords>
<Category>
<CategoryName>Renewable Energy</CategoryName>
<CategoryResIndex>1</CategoryResIndex>
<Group name="GHI">
<GroupLongTitle>
Horizontal Flat Plate Collectors: Global Horizontal Irradiance (GHI)
</GroupLongTitle>
<GroupOrder>2</GroupOrder>
<Layer name="ghi_nasa_low">
<LayerLongTitle>GHI NASA Low Resolution</LayerLongTitle>
<LayerShortTitle>GHI NASA Low</LayerShortTitle>
<LayerResolution>Low</LayerResolution>
<LayerResIndex>5</LayerResIndex>
<GraphLineColor>#0000FF</GraphLineColor>
<GraphLineWidth>1</GraphLineWidth>
<LayerHyperlink>eosweb.larc.nasa.gov/sse/</LayerHyperlink>
<AnnualMean>3.77</AnnualMean>
<Units>kWh/m sq</Units>
<MonthlyUnits>kWh/m sq</MonthlyUnits>
<Jan>1.83</Jan>
<Feb>2.68</Feb>
<Mar>3.67</Mar>
<Apr>4.46</Apr>
<May>5.43</May>
<Jun>5.77</Jun>
<Jul>5.58</Jul>
<Aug>4.92</Aug>
<Sep>4.11</Sep>
<Oct>3.12</Oct>
<Nov>2.07</Nov>
<Dec>1.55</Dec>
<JanMin>1.44</JanMin>
<FebMin>2.26</FebMin>
<MarMin>3.09</MarMin>
<AprMin>3.40</AprMin>
<MayMin>4.45</MayMin>
<JunMin>4.69</JunMin>
<JulMin>4.59</JulMin>
<AugMin>3.87</AugMin>
<SepMin>3.42</SepMin>
<OctMin>2.68</OctMin>
<NovMin>1.79</NovMin>
<DecMin>1.03</DecMin>
<JanMax>2.33</JanMax>
<FebMax>3.09</FebMax>
<MarMax>4.30</MarMax>
<AprMax>5.03</AprMax>
<MayMax>6.07</MayMax>
<JunMax>6.58</JunMax>
<JulMax>6.75</JulMax>
<AugMax>5.87</AugMax>
<SepMax>4.76</SepMax>
<OctMax>3.73</OctMax>
<NovMax>2.47</NovMax>
<DecMax>1.93</DecMax>
</Layer>
</Group>
<Group name="Wind">
<GroupLongTitle>Wind Speed at 50m Above Ground</GroupLongTitle>
<GroupOrder>4</GroupOrder>
<Layer name="wind_nasa_low">
<LayerLongTitle>Wind NASA Low Resolution</LayerLongTitle>
<LayerShortTitle>Wind NASA Low</LayerShortTitle>
<LayerResolution>Low</LayerResolution>
<LayerResIndex>5</LayerResIndex>
<WeibullK>-9999.00</WeibullK>
<GraphLineColor>#0000FF</GraphLineColor>
<GraphLineWidth>1</GraphLineWidth>
<LayerHyperlink>eosweb.larc.nasa.gov/sse/</LayerHyperlink>
<AnnualMean>-9999.00</AnnualMean>
<Units>W/m sq</Units>
<AnnualSpeed>6.56</AnnualSpeed>
<SpeedUnits>m/s</SpeedUnits>
<MonthlyUnits>m/s</MonthlyUnits>
<Jan>6.78</Jan>
<Feb>7.08</Feb>
<Mar>6.56</Mar>
<Apr>6.34</Apr>
<May>6.01</May>
<Jun>5.98</Jun>
<Jul>6.61</Jul>
<Aug>6.75</Aug>
<Sep>6.36</Sep>
<Oct>6.35</Oct>
<Nov>6.79</Nov>
<Dec>7.07</Dec>
<JanMin>-9999.00</JanMin>
<FebMin>-9999.00</FebMin>
<MarMin>-9999.00</MarMin>
<AprMin>-9999.00</AprMin>
<MayMin>-9999.00</MayMin>
<JunMin>-9999.00</JunMin>
<JulMin>-9999.00</JulMin>
<AugMin>-9999.00</AugMin>
<SepMin>-9999.00</SepMin>
<OctMin>-9999.00</OctMin>
<NovMin>-9999.00</NovMin>
<DecMin>-9999.00</DecMin>
<JanMax>-9999.00</JanMax>
<FebMax>-9999.00</FebMax>
<MarMax>-9999.00</MarMax>
<AprMax>-9999.00</AprMax>
<MayMax>-9999.00</MayMax>
<JunMax>-9999.00</JunMax>
<JulMax>-9999.00</JulMax>
<AugMax>-9999.00</AugMax>
<SepMax>-9999.00</SepMax>
<OctMax>-9999.00</OctMax>
<NovMax>-9999.00</NovMax>
<DecMax>-9999.00</DecMax>
</Layer>
</Group>
</Category>
</Data>
|
|
|
The SWERA Web Service also provides data downloads in HOMER format. Due to the unique format and information needed by the HOMER analysis tool, the SWERA Web Service when used with the HOMER format will ignore all other request parameters. The HOMER analysis tool only uses the GHI and Wind layers and at most one from each group for its analysis. For this reason, any more than one layer from either the GHI or Wind layers or another layer from another group of any kind will throw an error. Two common ways of using this format is to either specify one or two individual layers from the different groups or to use the "highestresolution" setting and request the two groups. Both types of requests are shown below.
Specifying Individual Layers:
http://na.unep.net/swera_ims/WS/index.php?coords=54.162434,-94.218750&format=HOMER&layers=ghi_nasa_low,wind_nasa_low
Using Highestresolution:
http://na.unep.net/swera_ims/WS/index.php?coords=54.162434,-94.218750&format=HOMER&layers=ghi,wind&highestresolution=on
For more information about the HOMER analysis tool and for a free download of the analysis software please see the HOMER Website .
|
|
These errors are returned from the SWERA Web Service if any of the request parameters are incorrect. An error code will be returned along with an error message in XML form.
| 100 | Coordinates not provided |
| 110 | Latitude point invalid |
| 120 | Longitude point invalid |
| 130 | The format of the coordinates <Coords> is wrong |
| 200 | Unknown Variable |
| 300 | Unknown Variable Value |
| 310 | Invalid Number of Values for Variable |
| 400 | Non-group Layer Used with Highest Resolution Variable |
| 410 | No Annual Attribute Used with Highest Resolution Variable |
|
|
