You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 44 Next »

Introduction

The FEWS PI-XML REST Service is hosted in a Tomcat service container. This service allows clients to interact with FEWS using a REST API.

Request parameters are marked in italics and the parameter types are given between parentheses. If not specified differently, a parameter is optional.

In case a REST resource is accessed with unknown query parameters an HTTP 400 response will be given informing the user a bad request was sent.

FEWS PI-XML REST Service API

GET timezoneid

Get ID of Configured timezone for the webservice.

Request parameters

  • not applicable

Response

  • String representation of time zone.

Example request

curl http://localhost:8080/FewsWebServices/rest/fewspiservice/v1/timezoneid

Example response

GMT

GET filters

Retrieve Pi Filters configuration from the Fews instance hosting the current FewsWebService.

Request parameters

    • filterId (string): Subset filter id.
    • documentVersion (string): File format version.

Response

    • PI Filters xml file content.

Example request

curl http://localhost:8080/FewsWebServices/rest/fewspiservice/v1/filters

Example response

<?xml version="1.0" encoding="UTF-8"?>
<filters xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.wldelft.nl/fews/PI" xsi:schemaLocation="http://www.wldelft.nl/fews/PI http://fews.wldelft.nl/schemas/version1.0/pi-schemas/pi_filter.xsd" version="1.23">
    <filter id="Countries">
        <name>Countries</name>
        <description></description>
        <child id="All">
            <name>All</name>
            <description></description>
        </child>
        <child id="Netherlands">
            <name>Netherlands</name>
            <description></description>
        </child>
    </filter>
</filters>


GET locations

Retrieve Pi Locations file containing all locations that are available for the passed 'filterId' argument. If not filterId is passed then all locations configured in the pre-defined filter will be returned.

 

Request parameters

  • filterId (string): Filter id.
  • documentVersion (string): File format version.

Response

  • Pi Locations XML file content.

Example request

curl http://localhost:8080/FewsWebServices/rest/fewspiservice/v1/locations

Example response

<?xml version="1.0" encoding="UTF-8"?>
<Locations xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.wldelft.nl/fews/PI" xsi:schemaLocation="http://www.wldelft.nl/fews/PI http://fews.wldelft.nl/schemas/version1.0/pi-schemas/pi_locations.xsd" version="1.23">
    <geoDatum>WGS 1984</geoDatum>
    <location locationId="10160355000">
        <description>SKIKDA</description>
        <shortName>SKIKDA</shortName>
        <lat>36.93</lat>
        <lon>6.95</lon>
        <x>6.95</x>
        <y>36.93</y>
        <z>7.0</z>
    </location>
    <location locationId="10160360000">
        <description>ANNABA</description>
        <shortName>ANNABA</shortName>
        <lat>36.83</lat>
        <lon>7.82</lon>
        <x>7.82</x>
        <y>36.83</y>
        <z>4.0</z>
    </location>
</Locations>


GET parameters

Retrieve Pi Parameters file containing all parameters that are available for the passed 'filterId' argument. If no filterId is passed then all parameters configured in the pre-defined filter will be returned.

 

Request parameters

  • documentVersion (string): File format version.

Response

  • PiTimeSeriesParameters XML file content 

Example request

curl http://localhost:8080/FewsWebServices/rest/fewspiservice/v1/parameters

Example response

<?xml version="1.0" encoding="UTF-8"?>
<timeseriesparameters xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.wldelft.nl/fews/PI" xsi:schemaLocation="http://www.wldelft.nl/fews/PI http://fews.wldelft.nl/schemas/version1.0/pi-schemas/pi_timeseriesparameters.xsd" version="1.23">
    <parameter id="T.obs.mean">
        <name>Observed Monthly Average Temperature</name>
        <parameterType>instantaneous</parameterType>
        <unit>oC</unit>
        <displayUnit>oC</displayUnit>
        <usesDatum>false</usesDatum>
    </parameter>
</timeseriesparameters>

GET timeseries

Returns a pi timeseries xml file containing the timeseries data filtered by the query parameters.

 

Request parameters

  • convertDatum (boolean): Convert values from relative location height to absolute height values. 
  • documentVersion (string, 1.9 or up): File format version (optional). For example: 1.23
  • endCreationTime (dateTime: yyyy-MM-ddTHH:mm:ssZ): End time of search period that looks for creation time of timeseries. Note: creation time of timeseries is actually the creation time of the task that produced/imported these timeseries.
  • endForecastTime (dateTime: yyyy-MM-ddTHH:mm:ssZ): End time of search period that looks for timeseries produced by forecasts that have their forecast time within this period.
  • endTime (dateTime: yyyy-MM-ddTHH:mm:ssZ): End time of search period that looks for timeseries values that lie within this period.
  • ensembleId (string): Ensemble identifier of for timeseries
  • externalForecastTimes (dateTime format: yyyy-MM-ddTHH:mm:ssZ): Time value of external forecast time. This parameter has to be duplicated to specify multiple multiple externalForecastTimes.
  • filterId (string): An existing subfilter of the default filter id.
  • forecastCount (integer): Number of forecast runs to return when using start- and end- forecast time. Default is 1.
  • locationIds (string): Subset of locations for which to retrieve timeseries. This parameter can be duplicated to use multiple locationIds.
  • moduleInstanceIds (string): Subset of moduleInstances for which to retrieve timeseries. This parameter can be duplicated to specify multiple moduleInstanceIds.
  • omitMissing (boolean): Toggle omitting or returning of missing values in response
  • onlyHeaders (boolean): Toggle to return only header information or also data
  • onlyForecasts (boolean): Toggle to return only forecast timeSeries (Since 2017.02)
  • parameterIds (boolean): Subset of parameters for which to retrieve timeseries. This parameter has to be duplicated to specify multiple parameters.
  • qualifierIds (boolean): Subset of qualifiers for which to retrieve timesieres. This parameter has to be duplicated to specify multiple qualifierIds.
  • showStatistics (boolean): Toggle to return statistics information about timeseries. Use in combination with 'onlyHeaders=true'. Returns additional information about data availability of timeseries (Since 2015.01)
  • showThresholds (boolean): Option to toggle the returning of threshold information in the headers
  • showEnsembleMemberIds (boolean): Show ensemble member ids.
  • startCreationTime (dateTime format: yyyy-MM-ddTHH:mm:ssZ): Start time of search period that looks for creation time of timeseries. Note: creation time of timeseries is actually the creation time of the task that produced/imported these timeseries.
  • startForecastTime (dateTime: yyyy-MM-ddTHH:mm:ssZ): Start time of search period that looks for timeseries produced by forecasts that have their forecast time within this period.
  • startTime (dateTime: yyyy-MM-ddTHH:mm:ssZ): Start time of search period that looks for timeseries values that lie within this period.
  • taskRunIds (string): Subset of task run ids for which to retrieve timeseries.  This parameter has to be duplicated to specify multiple taskRuns.
  • useDisplayUnits (boolean): Export values using display units.

Response

  • PiTimeseries xml file content.

Example request

curl http://localhost:8080/FewsWebServices/rest/fewspiservice/v1/timeseries?filterId=Netherlands&moduleInstanceIds=ImportObserved&startTime=2013-01-01T00:00:00Z&endTime=2014-01-01T00:00:00Z&convertDatum=false&useDisplayUnits=false&showThresholds=true&omitMissing=true&onlyHeaders=false&showEnsembleMemberIds=false&documentVersion=1.23&forecastCount=1

Example response

<?xml version="1.0" encoding="UTF-8"?>
<TimeSeries xmlns="http://www.wldelft.nl/fews/PI" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.wldelft.nl/fews/PI http://fews.wldelft.nl/schemas/version1.0/pi-schemas/pi_timeseries.xsd" version="1.23" xmlns:fs="http://www.wldelft.nl/fews/fs">
    <timeZone>0.0</timeZone>
    <series>
        <header>
            <type>instantaneous</type>
            <moduleInstanceId>ImportObserved</moduleInstanceId>
            <locationId>63306260000</locationId>
            <parameterId>T.obs.mean</parameterId>
            <timeStep unit="nonequidistant"/>
            <startDate date="2013-01-01" time="00:00:00"/>
            <endDate date="2014-01-01" time="00:00:00"/>
            <missVal>-999.0</missVal>
            <stationName>DE BILT</stationName>
            <lat>52.1</lat>
            <lon>5.18</lon>
            <x>5.18</x>
            <y>52.1</y>
            <z>15.0</z>
            <units>oC</units>
        </header>
        <event date="2013-01-01" time="00:00:00" value="2" flag="0"/>
        <event date="2013-02-01" time="00:00:00" value="1.7" flag="0"/>
        <event date="2013-03-01" time="00:00:00" value="2.5" flag="0"/>
        <event date="2013-04-01" time="00:00:00" value="8.1" flag="0"/>
        <event date="2013-05-01" time="00:00:00" value="11.5" flag="0"/>
        <event date="2013-06-01" time="00:00:00" value="15.3" flag="0"/>
        <event date="2013-07-01" time="00:00:00" value="19.2" flag="0"/>
        <event date="2013-08-01" time="00:00:00" value="18.1" flag="0"/>
        <event date="2013-09-01" time="00:00:00" value="14.4" flag="0"/>
        <event date="2013-10-01" time="00:00:00" value="12.2" flag="0"/>
        <event date="2013-11-01" time="00:00:00" value="6.7" flag="0"/>
        <event date="2013-12-01" time="00:00:00" value="5.9" flag="0"/>
        <event date="2014-01-01" time="00:00:00" value="5.7" flag="0"/>
    </series>
    <series>
        <header>
            <type>instantaneous</type>
            <moduleInstanceId>ImportObserved</moduleInstanceId>
            <locationId>63306380000</locationId>
            <parameterId>T.obs.mean</parameterId>
            <timeStep unit="nonequidistant"/>
            <startDate date="2013-01-01" time="00:00:00"/>
            <endDate date="2014-01-01" time="00:00:00"/>
            <missVal>-999.0</missVal>
            <stationName>MAASTRICHT AP</stationName>
            <lat>50.92</lat>
            <lon>5.78</lon>
            <x>5.78</x>
            <y>50.92</y>
            <z>116.0</z>
            <units>oC</units>
        </header>
        <event date="2013-01-01" time="00:00:00" value="1.8" flag="0"/>
        <event date="2013-02-01" time="00:00:00" value="0.8" flag="0"/>
        <event date="2013-03-01" time="00:00:00" value="2.4" flag="0"/>
        <event date="2013-04-01" time="00:00:00" value="9" flag="0"/>
        <event date="2013-05-01" time="00:00:00" value="11.5" flag="0"/>
        <event date="2013-06-01" time="00:00:00" value="15.7" flag="0"/>
        <event date="2013-07-01" time="00:00:00" value="20" flag="0"/>
        <event date="2013-08-01" time="00:00:00" value="18.5" flag="0"/>
        <event date="2013-09-01" time="00:00:00" value="14.4" flag="0"/>
        <event date="2013-10-01" time="00:00:00" value="12.5" flag="0"/>
        <event date="2013-11-01" time="00:00:00" value="5.8" flag="0"/>
        <event date="2013-12-01" time="00:00:00" value="5.6" flag="0"/>
        <event date="2014-01-01" time="00:00:00" value="5.7" flag="0"/>
    </series>
</TimeSeries>

 

 

POST timeseries

Write timeseries data to the FEWS system using the timeseries sets defined by the filters. The timeSeries are stored in the piTimeSeriesXmlContent. The 'convertDatum' argument is to allow timeseries that support a datum to have their values converted to a value relative to the location height. If values are already relative to location then enter FALSE or omit.

Request parameters

  • filterId (string): Filter id for when the input timeseries maps to multiple internal timeseries. Within the scope of the filter the input timeseries should only map to one internal timeseries.

  • convertDatum (boolean): Convert values from relative location height to absolute height values

Body parameters

  • piTimeSeriesXmlContent (xml string, required): PiTimeseries xml file content in application/x-www-form-urlencoded format. Example of a piTimeSeriesXmlContent:

  • <?xml version="1.0" encoding="UTF-8"?>
<TimeSeries xmlns="http://www.wldelft.nl/fews/PI" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
			xsi:schemaLocation="http://www.wldelft.nl/fews/PI http://fews.wldelft.nl/schemas/version1.0/pi-schemas/pi_timeseries.xsd" version="1.12">
	<timeZone>0.0</timeZone>
	<series>
		<header>
			<type>instantaneous</type>
			<locationId>63306260000</locationId>
			<parameterId>T.obs.mean</parameterId>
			<timeStep unit="nonequidistant"/>
			<startDate date="2013-01-01" time="00:40:00"/>
			<endDate date="2013-01-01" time="00:50:00"/>
			<missVal>-999.0</missVal>
			<stationName>DE BILT</stationName>
			<lat>51.76391247583424</lat>
			<lon>4.329717456157946</lon>
			<x>82000.0</x>
			<y>420000.0</y>
			<z>0.0</z>
			<units>m</units>
		</header>
		<event date="2013-01-01" time="00:40:00" value="13.0" flag="0"/>
		<event date="2013-01-01" time="00:50:00" value="13.0" flag="0"/>
	</series>
</TimeSeries>

Response

  • pi diag xml response with all diagnostic output.

Example request

The following example shows how timeSeries can created using the POST method. Take note that the TimeSeries have to be posted in PI XML Format in the body of the POST request using the piTimeSeriesXmlContent key. The value is the content of the PI XML Timeseries in application/x-www-form-urlencoded format.

curl http://localhost:8080/FewsWebServices/rest/fewspiservice/v1/timeseries/ -i -X POST -H 'Content-Type: application/x-www-form-urlencoded' -d piTimeSeriesXmlContent=%3C%3Fxml%20version%3D%221.0%22%20encoding%3D%22UTF-8%22%3F%3E%0D%0A%3CTimeSeries%20xmlns%3D%22http%3A%2F%2Fwww.wldelft.nl%2Ffews%2FPI%22%20xmlns%3Axsi%3D%22http%3A%2F%2Fwww.w3.org%2F2001%2FXMLSchema-instance%22%0D%0A%09%09%09xsi%3AschemaLocation%3D%22http%3A%2F%2Fwww.wldelft.nl%2Ffews%2FPI%20http%3A%2F%2Ffews.wldelft.nl%2Fschemas%2Fversion1.0%2Fpi-schemas%2Fpi_timeseries.xsd%22%20version%3D%221.12%22%3E%0D%0A%09%3CtimeZone%3E0.0%3C%2FtimeZone%3E%0D%0A%09%3Cseries%3E%0D%0A%09%09%3Cheader%3E%0D%0A%09%09%09%3Ctype%3Einstantaneous%3C%2Ftype%3E%0D%0A%09%09%09%3ClocationId%3E63306260000%3C%2FlocationId%3E%0D%0A%09%09%09%3CparameterId%3ET.obs.mean%3C%2FparameterId%3E%0D%0A%09%09%09%3CtimeStep%20unit%3D%22nonequidistant%22%2F%3E%0D%0A%09%09%09%3CstartDate%20date%3D%222013-01-01%22%20time%3D%2200%3A40%3A00%22%2F%3E%0D%0A%09%09%09%3CendDate%20date%3D%222013-01-01%22%20time%3D%2200%3A50%3A00%22%2F%3E%0D%0A%09%09%09%3CmissVal%3E-999.0%3C%2FmissVal%3E%0D%0A%09%09%09%3CstationName%3EDE%20BILT%3C%2FstationName%3E%0D%0A%09%09%09%3Clat%3E51.76391247583424%3C%2Flat%3E%0D%0A%09%09%09%3Clon%3E4.329717456157946%3C%2Flon%3E%0D%0A%09%09%09%3Cx%3E82000.0%3C%2Fx%3E%0D%0A%09%09%09%3Cy%3E420000.0%3C%2Fy%3E%0D%0A%09%09%09%3Cz%3E0.0%3C%2Fz%3E%0D%0A%09%09%09%3Cunits%3Em%3C%2Funits%3E%0D%0A%09%09%3C%2Fheader%3E%0D%0A%09%09%3Cevent%20date%3D%222013-01-01%22%20time%3D%2200%3A40%3A00%22%20value%3D%2213.0%22%20flag%3D%220%22%2F%3E%0D%0A%09%09%3Cevent%20date%3D%222013-01-01%22%20time%3D%2200%3A50%3A00%22%20value%3D%2213.0%22%20flag%3D%220%22%2F%3E%0D%0A%09%3C%2Fseries%3E%0D%0A%3C%2FTimeSeries%3E

Example response

<?xml version="1.0" encoding="UTF-8"?>
<Diag xmlns="http://www.wldelft.nl/fews/PI" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.wldelft.nl/fews/PI http://fews.
wldelft.nl/schemas/version1.0/pi-schemas/pi_diag.xsd" version="1.2">
    <line level="2" description="Multiple time series sets found for parameter=T.obs.mean location=63306260000"/>
    <line level="3" description="Import.Info: External time series successfully mapped to FEWS time series 63306260000 T.obs.mean   (m) nonequidistant Tue Jan 0
1 01:40:00 CET 2013 z=0.0"/>
    <line level="3" description="Import.info: 1 time series imported, 0 time series rejected"/>
    <line level="3" description="Import.info: The following locations-parameter combination imported  63306260000:T.obs.mean"/
</Diag>

 

GET taskruns

Request parameters

  • onlyForecasts (boolean): option to toggle if only forecasts should be returned. Default false.

  • onlyCurrent (boolean): option to toggle if only current forecasts should be returned. Default false.

  • startDispatchTime (dateTime: yyyy-MM-ddTHH:mm:ssZ): Start time of search period that looks for taskruns that have their dispatch time within this period.

  • endDispatchTime (dateTime: yyyy-MM-ddTHH:mm:ssZ): End time of search period that looks for taskruns that have their dispatch time within this period.

  • startForecastTime (dateTime: yyyy-MM-ddTHH:mm:ssZ): Start time of search period that looks for taskruns that have their forecast time within this period.

  • endForecastTime (dateTime: yyyy-MM-ddTHH:mm:ssZ): End time of search period that looks for taskruns that have their forecast time within this period.

  • workflowId (string): Filter by an existing workflow id.

  • scenarioId (string): Filter by an existing whatsif scenario id.

  • documentVersion (string, 1.9 or up): File format version (optional). For example: 1.23

Response

  • Pi TaskRuns xml file content.

Example request

curl http://localhost:8080/FewsWebServices/rest/fewspiservice/v1/taskruns?workflowId=ImportObserved

Example response

<?xml version="1.0" encoding="UTF-8"?>
<TaskRuns xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.wldelft.nl/fews/PI" xsi:schemaLocation="http://www.wldelft.nl/fews/PI http://fews.wldelft.nl/schemas/version1.0/pi-schemas/pi_taskruns.xsd" version="1.23">
    <timeZone>0.0</timeZone>
    <taskRun taskRunId="0_0">
        <forecast>false</forecast>
        <status>completed fully successful</status>
        <workflowId>ImportObserved</workflowId>
        <dispatchTime date="2017-08-13" time="09:55:18"/>
        <completionTime date="2017-08-13" time="10:21:35"/>
        <time0 date="2017-08-13" time="09:45:00"/>
        <outputStartTime date="1743-11-01" time="00:00:00"/>
        <outputEndTime date="2017-08-01" time="00:00:00"/>
        <user>rudie</user>
    </taskRun>
</TaskRuns>

 

GET taskrunstatus

Track the status of a workflow using the taskRunId.

Request parameters

  • taskId (string, required): task Id of a workflow.

  • maxWaitMillis (integer) time in milliseconds to wait for response

Response

Status of the workflow task. Possible response codes are:

  • I = Invalid,
  • P = Pending,
  • T = Terminated,
  • R = running,
  • F = Failed,
  • C = Completed fully successful,
  • D = Completed partly successful,
  • A = Approved,
  • B = Approved partly successful
  • null= No status available (produces when method call times-out)

Example request

curl localhost:8080/FewsWebServices/rest/fewspiservice/v1/taskrunstatus?documentVersion=1.23&taskId=1_0

Example response

C

 

POST runtask

Request parameters

  • workflowId (string, required): Identifier of the task to run
  • startTime (dateTime): Start of run period. Used for state selection period.
  • timeZero (dateTime): Forecast time zero. If missing System time is used (optional)
  • endTime (dateTime): End of run period. Used to define forecast length.
  • coldStateId (string): Id of a coldstate. Can be used to force state selection (optional).
  • scenarioId (string): Id of a predefined WhatIf scenario. Can be used to alter run parameters (optional).
  • userId (string) User id of the user that runs the task.
  • description (string): Descriptive text to identify run.

Body parameters

  • piParametersXml (piXML url encoded): Contents of a Pi ModelParameters XML file. PI ModelParameters can be exported by the General Adapter to provide information to external models being run by FEWS. The xml file content has to be in application/x-www-form-urlencoded format.

Response

  • String with the taskId of the task that is run.

Example request

curl http://localhost:8080/FewsWebServices/rest/fewspiservice/v1/runtask/?workflowId=ImportObserved&startTime=2014-01-01T00:00:00+0000&timeZero=2014-01-01T00:00:00+0000&endTime=2014-01-01T00:30:00+0000 -i -X POST -H 'Content-Type: application/x-www-form-urlencoded'  -d ''

Example response

10

 

GET timeseriesmodifiers

Request parameters

  • locationIds (string)

  • moduleInstanceIds (string)

  • startTime (dateTime)

  • endTime (dateTime)

  • userId (string)

  • modifierTypeId (string)

  • active (boolean, default true)

  • userDefinedModifierDescriptionKeyValuePair (string)

  • documentFormat (string)

Response

Example request

curl http://localhost:8080/FewsWebServices/rest/fewspiservice/v1/timeseriesmodifiers?onlyActiveModifiers=true

Example response

TODO

 

GET modifiers

Request parameters

  • not applicable

Response

Example request

curl http://localhost:8080/FewsWebServices/rest/fewspiservice/v1/modifiers?onlyActiveModifiers=true

Example response

TODO

 

POST modifiers

Request parameters

  • not applicable

Response

Example request

TODO

Example response

TODO

 

GET workflows

Request parameters

  • documentVersion (string, 1.9 or up): File format version (optional). For example: 1.23

Response

Example request

curl http://localhost:8080/FewsWebServices/rest/fewspiservice/v1/workflows

Example response

<?xml version="1.0" encoding="UTF-8"?>
<workflows xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.wldelft.nl/fews/PI" xsi:schemaLocation="http://www.wldelft.nl/fews/PI http://
fews.wldelft.nl/schemas/version1.0/pi-schemas/pi_workflows.xsd" version="1.23">
    <workflow id="ImportObserved">
        <name>Import Observed Data</name>
        <description>Import observed scalar data from external sources and process the imported data</description>
    </workflow>
</workflows>

 

GET samples

Request parameters

  • not applicable

Response

Example request

TODO

Example response

TODO

 

Configuration

The FewsPiService.properties file can be used to make service specific configurations available. This is a property file that is located in the FEWS configuration in the directory:

%REGION_HOME%/Config/PiClientConfigFiles/FewsPiService.properties

 

 

For more information about the possible properties, see FEWS Web Services configuration.

  • No labels

Disclaimer