In this primer we will demonstrate how to access and execute a remote prosessing service using the OGC Web Processing Service (WPS) protocol.
Find a data web source that hosts a WPS server, Deltares hosts a test server at http://dtvirt5.deltares.nl/wps/?
Ask for what the server has to offer with a standard WxS GetCapabilities call:
keyword |
value |
source |
---|---|---|
service |
WPS |
Mandatory WPS standard value |
version |
1.0.0 |
Optional for GetCapabilities |
request |
GetCapabilities |
Mandatory WPS standard value |
language |
Usually 'en' (English) |
Optional |
http://dtvirt5.deltares.nl/wps/? Request=GetCapabilities& Service=WPS |
This URL returns an xml file that contains an inventory of the available processes.
Inspect the overview of the content of a WPS server
Look at which WPS processes the server has to offer. For each process there is a tag ows:identifier
with an identifier and title of the process, as shown in the reduced xml file example below they are ogrbuffer
, constituents
, IDT_simple
and status_test
:
<wps:Capabilities xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:wps="http://www.opengis.net/wps/1.0.0" xmlns:ows="http://www.opengis.net/ows/1.1"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" service="WPS" version="1.0.0" xml:lang="en-CA" xsi:schemaLocation="http://www.opengis.net/wps/1.0.0 http://schemas.opengis.net/wps/1.0.0/wpsGetCapabilities_response.xsd" updateSequence="1"> <ows:ServiceIdentification> ... </ows:ServiceIdentification> <ows:ServiceProvider> ... </ows:ServiceProvider> ... <ows:HTTP> <ows:Get xlink:href="http://dtvirt5.deltares.nl/wps?"/> <ows:Post xlink:href="http://dtvirt5.deltares.nl/wps"/> </ows:HTTP> ... <wps:ProcessOfferings> <wps:Process wps:processVersion="0.1"> <ows:Identifier>ogrbuffer</ows:Identifier> <ows:Title>Buffer process using OGR</ows:Title> </wps:Process> ... <wps:Process wps:processVersion="1"> <ows:Identifier>constituents</ows:Identifier> <ows:Title>Lookup constituents based on their short name</ows:Title> </wps:Process> <wps:Process wps:processVersion="0.1"> <ows:Identifier>IDT_simple</ows:Identifier> <ows:Title>Interactive Dredge Planning Tool</ows:Title> </wps:Process> <wps:Process wps:processVersion="1"> <ows:Identifier>status_test</ows:Identifier> <ows:Title>echo</ows:Title> <ows:Abstract>Echo server</ows:Abstract> </wps:Process> </wps:ProcessOfferings> ... </wps:Capabilities> |
Where the GetCapabilities
request returns a full summary of the server's capatbilities, subsequently the DescribeProcess
request can be used to inquire about specific information on a single process:
keyword |
value |
source |
---|---|---|
service |
WPS |
Mandatory WPS standard value |
version |
1.0.0 |
Mandatory for DescribeProcess |
request |
DescribeProcess |
Mandatory WPS standard value |
identifer |
process name |
Mandatory parameter |
language |
Usually 'en' (English) |
Optional |
In this example we are going to use the constituents
process, below the URL for the DescribeProcess
request.
http://dtvirt5.deltares.nl/wps/? request=DescribeProcess& service=wps& version=1.0.0& identifier=constituents |
This URL will return an xml file that contains a description of the requested processes.
<wps:ProcessDescriptions xmlns:wps="http://www.opengis.net/wps/1.0.0" xmlns:ows="http://www.opengis.net/ows/1.1" xmlns:xlink="http://www.w3.org/1999/xlink"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.opengis.net/wps/1.0.0 http://schemas.opengis.net/wps/1.0.0/wpsDescribeProcess_response.xsd" service="WPS" version="1.0.0" xml:lang="en-CA"> <ProcessDescription wps:processVersion="1" storeSupported="false" statusSupported="false"> <ows:Identifier>constituents</ows:Identifier> <ows:Title>Lookup constituents based on their short name</ows:Title> <ows:Abstract> Lookup the speed of the constiuent based on the name of the constituent (following Doodson). </ows:Abstract> <DataInputs> <Input minOccurs="1" maxOccurs="1"> <ows:Identifier>date</ows:Identifier> <ows:Title>Date for which to calculate the nodal factors</ows:Title> <LiteralData> <ows:DataType ows:reference="http://www.w3.org/TR/xmlschema-2/#string">string</ows:DataType> <ows:AnyValue/> <DefaultValue/> </LiteralData> </Input> <Input minOccurs="1" maxOccurs="1"> <ows:Identifier>constituent</ows:Identifier> <ows:Title>Name of the constituent to look up (M2,...)</ows:Title> <LiteralData> <ows:DataType ows:reference="http://www.w3.org/TR/xmlschema-2/#string">string</ows:DataType> <ows:AnyValue/> </LiteralData> </Input> <Input minOccurs="1" maxOccurs="1"> <ows:Identifier>nodal</ows:Identifier> <ows:Title>Calculate nodal factors</ows:Title> <LiteralData> <ows:DataType ows:reference="http://www.w3.org/TR/xmlschema-2/#boolean">boolean</ows:DataType> <ows:AnyValue/> <DefaultValue>False</DefaultValue> </LiteralData> </Input> </DataInputs> <ProcessOutputs> <Output> <ows:Identifier>u</ows:Identifier> <ows:Title>u taken from Schureman</ows:Title> <LiteralOutput> <ows:DataType ows:reference="http://www.w3.org/TR/xmlschema-2/#float">float</ows:DataType> </LiteralOutput> </Output> <Output> <ows:Identifier>speed</ows:Identifier> <ows:Title>Speed of the constituent (radians per hour)</ows:Title> ... </Output> <Output> <ows:Identifier>FF</ows:Identifier> <ows:Title>FF nodal factor, taken from Schureman</ows:Title> <LiteralOutput> <ows:DataType ows:reference="http://www.w3.org/TR/xmlschema-2/#float">float</ows:DataType> </LiteralOutput> </Output> <Output> <ows:Identifier>VAU</ows:Identifier> <ows:Title>V+u taken from Schureman</ows:Title> <LiteralOutput> <ows:DataType ows:reference="http://www.w3.org/TR/xmlschema-2/#float">float</ows:DataType> </LiteralOutput> </Output> </ProcessOutputs> </ProcessDescription> </wps:ProcessDescriptions> |
In the DescribeProcess
document all information about the specific process is given. In the document general information is given in a title and abstract. Besides these also different in- and outputs are defined including titles, datatypes, default values, etc. In the document above we find three different inputs and four different outputs.
After finding out the required input parameters for the specific process, subsequently the Execute
request can be send:
keyword |
value |
source |
---|---|---|
service |
WPS |
Mandatory WPS standard value |
version |
1.0.0 |
Mandatory for Execute |
request |
Execute |
Mandatory WPS standard value |
identifer |
process name |
Mandatory parameter |
DataInputs |
inpute parameters |
Mandatory for Execute |
language |
Usually 'en' (English) |
Optional |
Since processes can contain multiple inputs, the DataInputs parameter looks somewhat different. The shape of this parameter is shown below. The different parameters are all after the equal sign (=) of datainputs and between brackets. The different parameters are separated by semicolons (;). Which input parameters are required and how these can be used is found in the DescribeProcess document, at the <ows:identifier> tag the identifier of the input parameter is given, this identifier is used in the URL.
datainputs=[parameter_1=5;parameter_2=9;parameter_3=false] |
For the purpose of this example only a single input value will be used in the execute request below.
http://dtvirt5.deltares.nl/wps/? request=Execute& service=wps& version=1.0.0& identifier=constituents& datainputs=[constituent=M2] |
The result of the Execute request is an XML document containing the different output parameters with corresponding output values.
<wps:ExecuteResponse xmlns:wps="http://www.opengis.net/wps/1.0.0" xmlns:ows="http://www.opengis.net/ows/1.1" xmlns:xlink="http://www.w3.org/1999/xlink"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.opengis.net/wps/1.0.0 http://schemas.opengis.net/wps/1.0.0/wpsExecute_response.xsd" service="WPS" version="1.0.0" xml:lang="en-CA" serviceInstance="http://dtvirt5.deltares.nl/wps?service=WPS&request=GetCapabilities&version=1.0.0" statusLocation="http://dtvirt5.deltares.nl/outputwps/pywps-137639971224.xml"> <wps:Process wps:processVersion="1"> <ows:Identifier>constituents</ows:Identifier> <ows:Title>Lookup constituents based on their short name</ows:Title> <ows:Abstract>...</ows:Abstract> </wps:Process> <wps:Status creationTime="2013-08-13T15:15:12Z"> <wps:ProcessSucceeded>PyWPS Process constituents successfully calculated</wps:ProcessSucceeded> </wps:Status> <wps:ProcessOutputs> <wps:Output> <ows:Identifier>u</ows:Identifier> <ows:Title>u taken from Schureman</ows:Title> <wps:Data> <wps:LiteralData dataType="float" uom="None">12.5910330876</wps:LiteralData> </wps:Data> </wps:Output> <wps:Output> <ows:Identifier>speed</ows:Identifier> <ows:Title>Speed of the constituent (radians per hour)</ows:Title> <wps:Data> <wps:LiteralData dataType="float" uom="r">0.505868049939</wps:LiteralData> </wps:Data> </wps:Output> <wps:Output> <ows:Identifier>FF</ows:Identifier> <ows:Title>FF nodal factor, taken from Schureman</ows:Title> <wps:Data> <wps:LiteralData dataType="float" uom="None">1.0281626242</wps:LiteralData> </wps:Data> </wps:Output> <wps:Output> <ows:Identifier>VAU</ows:Identifier> <ows:Title>V+u taken from Schureman</ows:Title> <wps:Data> <wps:LiteralData dataType="float" uom="None">16.2091031443</wps:LiteralData> </wps:Data> </wps:Output> </wps:ProcessOutputs> </wps:ExecuteResponse> |
The tidal_predict method supports both text/csv
and application/json
. The available attribute values are in the DescribeProcess
xml file.
<wps:ProcessDescriptions ...> <ProcessDescription ...> <ProcessOutputs> <Output><ows:Identifier>tide</ows:Identifier> <ows:Title>Calculated water level for requested locations and date</ows:Title><ComplexOutput> <Default> <Format><MimeType>text/csv</MimeType></Format> </Default> <Supported> <Format><MimeType>text/csv</MimeType></Format> <Format><MimeType>application/json</MimeType></Format> </Supported></ComplexOutput> </Output> </ProcessOutputs> </ProcessDescription> </wps:ProcessDescriptions> |
To get the non-default json output instead of the default csv output, add a keyword &responsedocument
(outside datainputs
brackets), using the WPS standard that you can specify attributes of a something by padding =@attributename=attributename
. In this case we add an attribute mimetype=application/json
to the output value tide
as &responsedocument=tide=@mimetype=application/json
, yielding the following url:
<?xml version="1.0" encoding="utf-8"?> ... http://dtvirt5.deltares.nl/wps?request=Execute&service=wps&version=1.0.0 &identifier=tidal_predict &datainputs=[location=LINESTRING%282%2052,3%2053%29; startdate=2020-01-01; enddate=2020-01-02] &responsedocument=tide=@mimetype=application/json |
Which gives:
<?xml version="1.0" encoding="utf-8"?> <wps:ExecuteResponse xmlns:wps="http://www.opengis.net/wps/1.0.0" xmlns:ows="http://www.opengis.net/ows/1.1" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.opengis.net/wps/1.0.0 http://schemas.opengis.net/wps/1.0.0/wpsExecute_response.xsd" service="WPS" version="1.0.0" xml:lang="en-CA" serviceInstance="http://dtvirt5.deltares.nl/wps?service=WPS&request=GetCapabilities&version=1.0.0"> <wps:Process wps:processVersion="0.1"> <ows:Identifier>tidal_predict</ows:Identifier> <ows:Title>Tidal prediction tool</ows:Title> <ows:Abstract> Tidal prediction tool can be used for different tidal prediction requests. Prediction is calculated from Topex/Poseidon dataset. Constitutuents provided by OSU TPXO. </ows:Abstract> </wps:Process> <wps:Status creationTime="2013-08-18T22:22:11Z"> <wps:ProcessSucceeded>PyWPS Process tidal_predict successfully calculated</wps:ProcessSucceeded> </wps:Status> <wps:ProcessOutputs> <wps:Output> <ows:Identifier>tide</ows:Identifier> <ows:Title>Calculated water level for requested locations and date</ows:Title> <wps:Data> <wps:ComplexData mimeType="application/json"> [{"date":1577836800000000000,"h":0.9055217703,"lat":52.0,"lon":2.0},{"date":1577840400000000000,"h":0.5269456712,"lat":52.0,"lon":2.0},{"date":1577844000000000000,"h":-0.0264890836,"lat":52.0,"lon":2.0},{"date":1577847600000000000,"h":-0.5541336177,"lat":52.0,"lon":2.0},{"date":1577851200000000000,"h":-0.9109530928,"lat":52.0,"lon":2.0},{"date":1577854800000000000,"h":-1.0493201774,"lat":52.0,"lon":2.0},{"date":1577858400000000000,"h":-0.9827940939,"lat":52.0,"lon":2.0},{"date":1577862000000000000,"h":-0.7274707407,"lat":52.0,"lon":2.0},{"date":1577865600000000000,"h":-0.2892092144,"lat":52.0,"lon":2.0},{"date":1577869200000000000,"h":0.2907139097,"lat":52.0,"lon":2.0},{"date":1577872800000000000,"h":0.8872141613,"lat":52.0,"lon":2.0},{"date":1577876400000000000,"h":1.3083130215,"lat":52.0,"lon":2.0},{"date":1577880000000000000,"h":1.3872365816,"lat":52.0,"lon":2.0},{"date":1577883600000000000,"h":1.085052368,"lat":52.0,"lon":2.0},{"date":1577887200000000000,"h":0.5201416491,"lat":52.0,"lon":2.0},{"date":1577890800000000000,"h":-0.1020110267,"lat":52.0,"lon":2.0},{"date":1577894400000000000,"h":-0.6028626472,"lat":52.0,"lon":2.0},{"date":1577898000000000000,"h":-0.9006199205,"lat":52.0,"lon":2.0},{"date":1577901600000000000,"h":-0.9942235126,"lat":52.0,"lon":2.0},{"date":1577905200000000000,"h":-0.8999725194,"lat":52.0,"lon":2.0},{"date":1577908800000000000,"h":-0.6170361442,"lat":52.0,"lon":2.0},{"date":1577912400000000000,"h":-0.1592478845,"lat":52.0,"lon":2.0},{"date":1577916000000000000,"h":0.3852466596,"lat":52.0,"lon":2.0},{"date":1577919600000000000,"h":0.8422715702,"lat":52.0,"lon":2.0},{"date":1577923200000000000,"h":1.0239596024,"lat":52.0,"lon":2.0},{"date":1577836800000000000,"h":0.3589546692,"lat":53.0,"lon":3.0},{"date":1577840400000000000,"h":0.1607531366,"lat":53.0,"lon":3.0},{"date":1577844000000000000,"h":-0.1128007448,"lat":53.0,"lon":3.0},{"date":1577847600000000000,"h":-0.360735561,"lat":53.0,"lon":3.0},{"date":1577851200000000000,"h":-0.5135657472,"lat":53.0,"lon":3.0},{"date":1577854800000000000,"h":-0.5523997776,"lat":53.0,"lon":3.0},{"date":1577858400000000000,"h":-0.488455418,"lat":53.0,"lon":3.0},{"date":1577862000000000000,"h":-0.332647575,"lat":53.0,"lon":3.0},{"date":1577865600000000000,"h":-0.0899128505,"lat":53.0,"lon":3.0},{"date":1577869200000000000,"h":0.2167441457,"lat":53.0,"lon":3.0},{"date":1577872800000000000,"h":0.5221087736,"lat":53.0,"lon":3.0},{"date":1577876400000000000,"h":0.72895627,"lat":53.0,"lon":3.0},{"date":1577880000000000000,"h":0.7560079569,"lat":53.0,"lon":3.0},{"date":1577883600000000000,"h":0.5892076622,"lat":53.0,"lon":3.0},{"date":1577887200000000000,"h":0.2938556551,"lat":53.0,"lon":3.0},{"date":1577890800000000000,"h":-0.0239550777,"lat":53.0,"lon":3.0},{"date":1577894400000000000,"h":-0.276009934,"lat":53.0,"lon":3.0},{"date":1577898000000000000,"h":-0.425450966,"lat":53.0,"lon":3.0},{"date":1577901600000000000,"h":-0.475583489,"lat":53.0,"lon":3.0},{"date":1577905200000000000,"h":-0.4359643097,"lat":53.0,"lon":3.0},{"date":1577908800000000000,"h":-0.3055336229,"lat":53.0,"lon":3.0},{"date":1577912400000000000,"h":-0.0905682739,"lat":53.0,"lon":3.0},{"date":1577916000000000000,"h":0.1642704437,"lat":53.0,"lon":3.0},{"date":1577919600000000000,"h":0.3712641261,"lat":53.0,"lon":3.0},{"date":1577923200000000000,"h":0.4383804482,"lat":53.0,"lon":3.0}] </wps:ComplexData> </wps:Data> </wps:Output> </wps:ProcessOutputs> </wps:ExecuteResponse> |
The service is validated with the timeseries from live.getij.nl (Dutch tidal information)