Introduction
The FEWS PI REST Web Service is hosted in a Tomcat application server. This service allows clients to interact with FEWS using a REST API. The REST Service will return PI-XML by default.
Since FEWS 2017.02 the PI-JSON format is supported as well for the following GET methods: filters, parameters, locations and parameters. For more information on the PI-JSON format, see: FEWS PI-JSON format. For some examples on how to use the the FEWS PI-JSON REST Web service see FEWS PI-JSON REST Examples.
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 REST Web 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.
Request parameters
- filterId (string): Subset filter id.
- documentVersion (string): File format version.
- documentFormat (string): PI_XML (default) or PI_JSON
Response
- Filters PI-XML or PI-JSON file content.
Example request
curl "http://localhost:8080/FewsWebServices/rest/fewspiservice/v1/filters"
Example PI-XML 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. The geoDatum used in the response is determined by the geoDatum configured in the locations.xml.
Request parameters
- filterId (string): Filter id.
- documentVersion (string): File format version.
- documentFormat (string): PI_XML (default) or PI_JSON
- showAttributes (boolean) Since 2017.02: toggle to show location attributes.
- includeLocationRelations (boolean) Since 2019.02: toggle to include locationRelations. Optional, default is false. For xml format avalable from version 1.26 or higher.
- includeTimeDependency (boolean) Since 2019.02: toggle to include timeDependency. Optional, default is false. For xml format avalable from version 1.26 or higher.
Response
- Locations PI-XML or PI-JSON file content.
Example request
curl "http://localhost:8080/FewsWebServices/rest/fewspiservice/v1/locations?showAttributes=true&documentVersion=1.24"
Example PI-XML 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.24">
<geoDatum>WGS 1984</geoDatum>
<location locationId="locA">
<shortName>A</shortName>
<lat>9.0</lat>
<lon>9.0</lon>
<x>9.0</x>
<y>9.0</y>
<z>9.0</z>
<relation id="UPSTREAM">
<relatedLocationId>locB</relatedLocationId>
</relation>
<relation id="UPSTREAM">
<relatedLocationId>locC</relatedLocationId>
</relation>
<attribute id="TEST_ATTRIBUTE" name="TEST_ATTRIBUTE">
<startDateTime>1890-01-01T00:00:00+0000</startDateTime>
<endDateTime>1950-01-01T00:00:00+0000</endDateTime>
<text>A1</text>
</attribute>
<attribute id="TEST_ATTRIBUTE" name="TEST_ATTRIBUTE">
<startDateTime>1950-01-01T00:00:00+0000</startDateTime>
<text>A2</text>
</attribute>
</location>
<location locationId="locB">
<shortName>B</shortName>
<lat>7.0</lat>
<lon>7.0</lon>
<x>7.0</x>
<y>7.0</y>
<z>7.0</z>
<relation id="UPSTREAM">
<relatedLocationId>locC</relatedLocationId>
<startDateTime>1930-01-01T00:00:00+0000</startDateTime>
<endDateTime>1980-01-01T00:00:00+0000</endDateTime>
</relation>
<relation id="UPSTREAM">
<relatedLocationId>locF</relatedLocationId>
<endDateTime>1980-01-01T00:00:00+0000</endDateTime>
</relation>
<relation id="UPSTREAM">
<relatedLocationId>locE</relatedLocationId>
<startDateTime>1930-01-01T00:00:00+0000</startDateTime>
</relation>
<attribute id="TEST_ATTRIBUTE" name="TEST_ATTRIBUTE">
<startDateTime>1930-01-01T00:00:00+0000</startDateTime>
<endDateTime>2000-01-01T00:00:00+0000</endDateTime>
<text>B</text>
</attribute>
</location>
<location locationId="locC">
<shortName>C</shortName>
<lat>5.0</lat>
<lon>5.0</lon>
<x>5.0</x>
<y>5.0</y>
<z>5.0</z>
</location>
<location locationId="locD">
<shortName>D</shortName>
<lat>3.0</lat>
<lon>3.0</lon>
<x>3.0</x>
<y>3.0</y>
<z>3.0</z>
<relation id="UPSTREAM">
<relatedLocationId>locB</relatedLocationId>
</relation>
<relation id="UPSTREAM">
<relatedLocationId>locE</relatedLocationId>
</relation>
<attribute id="TEST_ATTRIBUTE" name="TEST_ATTRIBUTE">
<startDateTime>1930-01-01T00:00:00+0000</startDateTime>
<endDateTime>1980-01-01T00:00:00+0000</endDateTime>
<text>D</text>
</attribute>
</location>
<location locationId="locE">
<shortName>E</shortName>
<lat>2.0</lat>
<lon>2.0</lon>
<x>2.0</x>
<y>2.0</y>
<z>2.0</z>
<relation id="UPSTREAM">
<relatedLocationId>locF</relatedLocationId>
</relation>
<attribute id="TEST_ATTRIBUTE" name="TEST_ATTRIBUTE">
<startDateTime>1910-01-01T00:00:00+0000</startDateTime>
<endDateTime>1930-01-01T00:00:00+0000</endDateTime>
<text>E1</text>
</attribute>
<attribute id="TEST_ATTRIBUTE" name="TEST_ATTRIBUTE">
<startDateTime>1930-01-01T00:00:00+0000</startDateTime>
<endDateTime>1950-01-01T00:00:00+0000</endDateTime>
<text>E2</text>
</attribute>
<attribute id="TEST_ATTRIBUTE" name="TEST_ATTRIBUTE">
<startDateTime>1950-01-01T00:00:00+0000</startDateTime>
<endDateTime>1980-01-01T00:00:00+0000</endDateTime>
<text>E3</text>
</attribute>
</location>
<location locationId="locF">
<shortName>F</shortName>
<lat>1.0</lat>
<lon>1.0</lon>
<x>1.0</x>
<y>1.0</y>
<z>1.0</z>
<attribute id="TEST_ATTRIBUTE" name="TEST_ATTRIBUTE">
<text>F</text>
</attribute>
</location>
</Locations>
Example PI-JSON response
{
"version" : "1.26",
"geoDatum" : "WGS 1984",
"locations" : [ {
"locationId" : "locA",
"shortName" : "A",
"lat" : "9.0",
"lon" : "9.0",
"x" : "9.0",
"y" : "9.0",
"z" : "9.0",
"attributes" : [ {
"name" : "TEST_ATTRIBUTE",
"type" : "text",
"id" : "TEST_ATTRIBUTE",
"startDateTime" : "1890-01-01T00:00:00+0000",
"endDateTime" : "1950-01-01T00:00:00+0000",
"value" : "A1"
}, {
"name" : "TEST_ATTRIBUTE",
"type" : "text",
"id" : "TEST_ATTRIBUTE",
"startDateTime" : "1950-01-01T00:00:00+0000",
"value" : "A2"
} ],
"relations" : [ {
"id" : "UPSTREAM",
"relatedLocationId" : "locB"
}, {
"id" : "UPSTREAM",
"relatedLocationId" : "locC"
} ]
}, {
"locationId" : "locB",
"shortName" : "B",
"lat" : "7.0",
"lon" : "7.0",
"x" : "7.0",
"y" : "7.0",
"z" : "7.0",
"attributes" : [ {
"name" : "TEST_ATTRIBUTE",
"type" : "text",
"id" : "TEST_ATTRIBUTE",
"startDateTime" : "1930-01-01T00:00:00+0000",
"endDateTime" : "2000-01-01T00:00:00+0000",
"value" : "B"
} ],
"relations" : [ {
"id" : "UPSTREAM",
"relatedLocationId" : "locC",
"startDateTime" : "1930-01-01T00:00:00+0000",
"endDateTime" : "1980-01-01T00:00:00+0000"
}, {
"id" : "UPSTREAM",
"relatedLocationId" : "locF",
"endDateTime" : "1980-01-01T00:00:00+0000"
}, {
"id" : "UPSTREAM",
"relatedLocationId" : "locE",
"startDateTime" : "1930-01-01T00:00:00+0000"
} ]
}, {
"locationId" : "locC",
"shortName" : "C",
"lat" : "5.0",
"lon" : "5.0",
"x" : "5.0",
"y" : "5.0",
"z" : "5.0",
"attributes" : [ ],
"relations" : [ ]
}, {
"locationId" : "locD",
"shortName" : "D",
"lat" : "3.0",
"lon" : "3.0",
"x" : "3.0",
"y" : "3.0",
"z" : "3.0",
"attributes" : [ {
"name" : "TEST_ATTRIBUTE",
"type" : "text",
"id" : "TEST_ATTRIBUTE",
"startDateTime" : "1930-01-01T00:00:00+0000",
"endDateTime" : "1980-01-01T00:00:00+0000",
"value" : "D"
} ],
"relations" : [ {
"id" : "UPSTREAM",
"relatedLocationId" : "locB"
}, {
"id" : "UPSTREAM",
"relatedLocationId" : "locE"
} ]
}, {
"locationId" : "locE",
"shortName" : "E",
"lat" : "2.0",
"lon" : "2.0",
"x" : "2.0",
"y" : "2.0",
"z" : "2.0",
"attributes" : [ {
"name" : "TEST_ATTRIBUTE",
"type" : "text",
"id" : "TEST_ATTRIBUTE",
"startDateTime" : "1910-01-01T00:00:00+0000",
"endDateTime" : "1930-01-01T00:00:00+0000",
"value" : "E1"
}, {
"name" : "TEST_ATTRIBUTE",
"type" : "text",
"id" : "TEST_ATTRIBUTE",
"startDateTime" : "1930-01-01T00:00:00+0000",
"endDateTime" : "1950-01-01T00:00:00+0000",
"value" : "E2"
}, {
"name" : "TEST_ATTRIBUTE",
"type" : "text",
"id" : "TEST_ATTRIBUTE",
"startDateTime" : "1950-01-01T00:00:00+0000",
"endDateTime" : "1980-01-01T00:00:00+0000",
"value" : "E3"
} ],
"relations" : [ {
"id" : "UPSTREAM",
"relatedLocationId" : "locF"
} ]
}, {
"locationId" : "locF",
"shortName" : "F",
"lat" : "1.0",
"lon" : "1.0",
"x" : "1.0",
"y" : "1.0",
"z" : "1.0",
"attributes" : [ {
"name" : "TEST_ATTRIBUTE",
"type" : "text",
"id" : "TEST_ATTRIBUTE",
"value" : "F"
} ],
"relations" : [ ]
} ]
}
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.
- documentFormat (string): PI_XML (default) or PI_JSON
Response
- Parameters PI-XML or PI-JSON file content.
Example request
curl "http://localhost:8080/FewsWebServices/rest/fewspiservice/v1/parameters"
Example PI-XML 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.25">
<parameter id="T.obs.mean" parameterGroup="Temperature">
<name>Observed Monthly Average Temperature</name>
<parameterType>instantaneous</parameterType>
<unit>oC</unit>
<displayUnit>oC</displayUnit>
<usesDatum>false</usesDatum>
</parameter>
</timeseriesparameters>
Example PI-JSON response
{
"version" : "1.25",
"timeSeriesParameters" : [ {
"id" : "T.obs.mean",
"name" : "Observed Monthly Average Temperature",
"parameterType" : "instantaneous",
"unit" : "oC",
"displayUnit" : "oC",
"usesDatum" : "false",
"parameterGroup" : "Temperature"
} ]
}
GET timeseries
Returns a pi timeseries xml file containing the time series 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
- documentFormat (string): PI_XML (default) or PI_JSON
- endCreationTime (dateTime: yyyy-MM-ddTHH:mm:ssZ): End time of search period that looks for creation time of time series. Note: creation time of time series is actually the creation time of the task that produced/imported these time series.
- endForecastTime (dateTime: yyyy-MM-ddTHH:mm:ssZ): End time of search period that looks for time series 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 time series values that lie within this period.
- ensembleId (string): Ensemble identifier of for time series
- 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. N.B. Can be used in combination with taskRunIds since 2020.01.
- 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 time series. This parameter can be duplicated to use multiple locationIds.
- moduleInstanceIds (string): Subset of moduleInstances for which to retrieve time series. 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 time series (Since 2017.02)
- onlyManualEdits (boolean): Toggle to return only manual edits.
- parameterIds (string): Subset of parameters for which to retrieve time series. This parameter has to be duplicated to specify multiple parameters.
- qualifierIds (string): Subset of qualifiers for which to retrieve time series. This parameter has to be duplicated to specify multiple qualifierIds.
- showProducts (boolean): Toggle to display product information that is assigned to a forecast. (Since 2019.02). See below for an example.
- showStatistics (boolean): Toggle to return statistics information about time series. Typically used in combination with onlyHeaders. Returns additional information about data availability of time series (Since 2015.01).
- firstValueTime: First time with a value in the time series
- lastValueTime: Last time with a value in the time series
- maxValue: Maximum value in the time series
- minValue: Minimum value in the time series
- valueCount: Number of values in the time series
- showThresholds (boolean): Option to toggle the returning of threshold information in the headers
- showEnsembleMemberIds (boolean): Show ensemble member ids instead of ensemble member indices.
- timeSeriesType (string): Explicitly filter on a specific time series type. (Since 2020.01). Possible values are: EXTERNAL_HISTORICAL, EXTERNAL_FORECASTING, SIMULATED_HISTORICAL, SIMULATED_FORECASTING.
- thinning (long): unit ms/pixel. Thinning is used to retrieve the visually interesting time steps of time series. It tries to keep the peaks and gaps and minimizes the number of time steps that have to be retrieved. It is typically used for visualizations. The value to be specified should be equal to the view period in milliseconds of the time series that is visualized divided by the number of pixels that are available for display. For example: visualizing a view period of 5 years (157784760000 milliseconds) on a display of 1024 pixels, the thinning parameter should be set to 157784760000/1024 = 15408668. (Since 2019.02)
- useMilliseconds (boolean) Optional argument. Default is false. If it is set to true, the response will contain milliseconds. See example below. Available in 2017.02 and from 2019.02
- startCreationTime (dateTime format: yyyy-MM-ddTHH:mm:ssZ): Start time of search period that looks for creation time of time series. Note: creation time of time series is actually the creation time of the task that produced/imported these time series.
- startForecastTime (dateTime: yyyy-MM-ddTHH:mm:ssZ): Start time of search period that looks for time series 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 time series values that lie within this period.
- taskRunIds (string): Subset of task run ids for which to retrieve time series. This parameter has to be duplicated to specify multiple taskRuns. N.B. cannot be used in combination with a filterId.
- useDisplayUnits (boolean): Export values using display units.
- importFromExternalDataSource (boolean, default true): import data from external data source (Archive). (since 2017.02)
- timeStepId (string): filter time series by the timestep that has been configured in the TimeSteps.xml. (since 2018.02). N.B.: It is not required to use the timeStepId's in the filter configurations to be able to use them as long as they have been configured in the TimeSteps.xml.
Response
- Time series PI-XML or PI-JSON file content..
Filter combinations
Not all parameters can be combined. The following combinations are commonly used valid combinations of parameters. The main way to filter timeSeries is by using filterIds or taskRunIds.
filterId Only the default filter or one of its subfilters can be applied) | taskRunIds One or more taskRunIds can be specified | startTime, endTime | startCreationTime, endCreationTime | startForecastTime, endForecastTime | |
|---|---|---|---|---|---|
| Apply a filter to the time series. The requested period will be set to the current time minus one day and one hour ago until the current time plus one day and one hour | X(1) | ||||
| Get all time series created by one or more taskRuns. All time steps of the matching time series are returned. | X | ||||
| Get the time series created by a taskrun and apply a filter from the Filters configuration. startTime and endTime cannot be specified. The complete time series will be returned. Since 2020.01. | X | X | |||
| Apply a filter to the time series and return time steps that are in the startTime and endTime range. | X | X | |||
| Apply a filter to the time series. Only time series created during the startCreationTime and endCreationTime and part of the filter will be returned. All time steps of the matching time series are returned. | X | X | |||
| Apply a filter to the time series. Return only time series created during the creation time period. Only return timesteps in the startTime and endTime range. | X | X | X | ||
| Apply a filter to the time series. Return only time series with external forecast times in the startForecastTime and endForecastTime period. Only return timesteps in the startTime and endTime range. | X | X | X | ||
| Apply a filter to the time series. Return only time series with external forecast times in the startForecastTime and endForecastTime period that were created in the creation time period. Only return time steps in the startTime and endTime range. | X | X | X | X | |
| Apply a filter to the time series. Return only time series created during the creation time period. All time steps of the matching time series are returned. | X | X | |||
| Apply a filter to the time series. Return only time series with external forecast times in the startForecastTime and endForecastTime period. All time steps of the matching time series are returned. | X | X | |||
| Apply a filter to the time series. Return only time series with external forecast times in the startForecastTime and endForecastTime period. All time steps of the matching time series are returned. | X | X | X |
(1): Take note that if no startTime and endTime are specified, the requested period will be set to the current time minus one day and one hour ago until the current time plus one day and one hour.
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 PI-XML 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>
PI-XML example with useMilliseconds enabled
<?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.250" value="2" flag="0"/>
<event date="2013-02-01" time="00:00:00.250" value="1.7" flag="0"/>
<event date="2013-03-01" time="00:00:00.250" value="2.5" flag="0"/>
<event date="2013-04-01" time="00:00:00.250" value="8.1" flag="0"/>
<event date="2013-05-01" time="00:00:00.250" value="11.5" flag="0"/>
<event date="2013-06-01" time="00:00:00.250" value="15.3" flag="0"/>
<event date="2013-07-01" time="00:00:00.250" value="19.2" flag="0"/>
<event date="2013-08-01" time="00:00:00.250" value="18.1" flag="0"/>
<event date="2013-09-01" time="00:00:00.250" value="14.4" flag="0"/>
<event date="2013-10-01" time="00:00:00.250" value="12.2" flag="0"/>
<event date="2013-11-01" time="00:00:00.250" value="6.7" flag="0"/>
<event date="2013-12-01" time="00:00:00.250" value="5.9" flag="0"/>
<event date="2014-01-01" time="00:00:00.250" value="5.7" flag="0"/>
</series>
</TimeSeries>
PI-XML example with showProducts enabled (snippet).
<product id="aProduct" name="A Product">
<productDate date="2019-06-25" time="11:31:59"/>
<category id="Meteo" name="Meteo"/>
<productInfo>
<user>Rudie Ekkelenkamp</user>
<confidence>MEDIUM</confidence>
<classification>INTERNAL</classification>
<comment>My product comment</comment>
</productInfo>
</product>
Example PI-JSON response
{
"version" : "1.23",
"timeZone" : "0.0",
"timeSeries" : [ {
"header" : {
"type" : "instantaneous",
"moduleInstanceId" : "ImportObserved",
"locationId" : "63306260000",
"parameterId" : "T.obs.mean",
"timeStep" : {
"unit" : "nonequidistant"
},
"startDate" : {
"date" : "2013-01-01",
"time" : "00:00:00"
},
"endDate" : {
"date" : "2014-01-01",
"time" : "00:00:00"
},
"missVal" : "-999.0",
"stationName" : "DE BILT",
"lat" : "52.1",
"lon" : "5.18",
"x" : "5.18",
"y" : "52.1",
"z" : "15.0",
"units" : "oC"
},
"events" : [ {
"date" : "2013-01-01",
"time" : "00:00:00",
"value" : "2",
"flag" : "0"
}, {
"date" : "2013-02-01",
"time" : "00:00:00",
"value" : "1.7",
"flag" : "0"
}, {
"date" : "2013-03-01",
"time" : "00:00:00",
"value" : "2.5",
"flag" : "0"
}, {
"date" : "2013-04-01",
"time" : "00:00:00",
"value" : "8.1",
"flag" : "0"
}, {
"date" : "2013-05-01",
"time" : "00:00:00",
"value" : "11.5",
"flag" : "0"
}, {
"date" : "2013-06-01",
"time" : "00:00:00",
"value" : "15.3",
"flag" : "0"
}, {
"date" : "2013-07-01",
"time" : "00:00:00",
"value" : "19.2",
"flag" : "0"
}, {
"date" : "2013-08-01",
"time" : "00:00:00",
"value" : "18.1",
"flag" : "0"
}, {
"date" : "2013-09-01",
"time" : "00:00:00",
"value" : "14.4",
"flag" : "0"
}, {
"date" : "2013-10-01",
"time" : "00:00:00",
"value" : "12.2",
"flag" : "0"
}, {
"date" : "2013-11-01",
"time" : "00:00:00",
"value" : "6.7",
"flag" : "0"
}, {
"date" : "2013-12-01",
"time" : "00:00:00",
"value" : "5.9",
"flag" : "0"
}, {
"date" : "2014-01-01",
"time" : "00:00:00",
"value" : "5.7",
"flag" : "0"
} ]
}, {
"header" : {
"type" : "instantaneous",
"moduleInstanceId" : "ImportObserved",
"locationId" : "63306380000",
"parameterId" : "T.obs.mean",
"timeStep" : {
"unit" : "nonequidistant"
},
"startDate" : {
"date" : "2013-01-01",
"time" : "00:00:00"
},
"endDate" : {
"date" : "2014-01-01",
"time" : "00:00:00"
},
"missVal" : "-999.0",
"stationName" : "MAASTRICHT AP",
"lat" : "50.92",
"lon" : "5.78",
"x" : "5.78",
"y" : "50.92",
"z" : "116.0",
"units" : "oC"
},
"events" : [ {
"date" : "2013-01-01",
"time" : "00:00:00",
"value" : "1.8",
"flag" : "0"
}, {
"date" : "2013-02-01",
"time" : "00:00:00",
"value" : "0.8",
"flag" : "0"
}, {
"date" : "2013-03-01",
"time" : "00:00:00",
"value" : "2.4",
"flag" : "0"
}, {
"date" : "2013-04-01",
"time" : "00:00:00",
"value" : "9",
"flag" : "0"
}, {
"date" : "2013-05-01",
"time" : "00:00:00",
"value" : "11.5",
"flag" : "0"
}, {
"date" : "2013-06-01",
"time" : "00:00:00",
"value" : "15.7",
"flag" : "0"
}, {
"date" : "2013-07-01",
"time" : "00:00:00",
"value" : "20",
"flag" : "0"
}, {
"date" : "2013-08-01",
"time" : "00:00:00",
"value" : "18.5",
"flag" : "0"
}, {
"date" : "2013-09-01",
"time" : "00:00:00",
"value" : "14.4",
"flag" : "0"
}, {
"date" : "2013-10-01",
"time" : "00:00:00",
"value" : "12.5",
"flag" : "0"
}, {
"date" : "2013-11-01",
"time" : "00:00:00",
"value" : "5.8",
"flag" : "0"
}, {
"date" : "2013-12-01",
"time" : "00:00:00",
"value" : "5.6",
"flag" : "0"
}, {
"date" : "2014-01-01",
"time" : "00:00:00",
"value" : "5.7",
"flag" : "0"
} ]
} ]
}
Example Json with milliseconds:
{
"version" : "1.23",
"timeZone" : "0.0",
"timeSeries" : [ {
"header" : {
"type" : "instantaneous",
"moduleInstanceId" : "ImportObserved",
"locationId" : "63306260000",
"parameterId" : "T.obs.mean",
"timeStep" : {
"unit" : "nonequidistant"
},
"startDate" : {
"date" : "2013-01-01",
"time" : "00:00:00"
},
"endDate" : {
"date" : "2014-01-01",
"time" : "00:00:00"
},
"missVal" : "-999.0",
"stationName" : "DE BILT",
"lat" : "52.1",
"lon" : "5.18",
"x" : "5.18",
"y" : "52.1",
"z" : "15.0",
"units" : "oC"
},
"events" : [ {
"date" : "2013-01-01",
"time" : "00:00:00.250",
"value" : "2",
"flag" : "0"
}, {
"date" : "2013-02-01",
"time" : "00:00:00.250",
"value" : "1.7",
"flag" : "0"
}, {
"date" : "2013-03-01",
"time" : "00:00:00.250",
"value" : "2.5",
"flag" : "0"
}, {
"date" : "2013-04-01",
"time" : "00:00:00.250",
"value" : "8.1",
"flag" : "0"
}, {
"date" : "2013-05-01",
"time" : "00:00:00.250",
"value" : "11.5",
"flag" : "0"
}, {
"date" : "2013-06-01",
"time" : "00:00:00.250",
"value" : "15.3",
"flag" : "0"
}, {
"date" : "2013-07-01",
"time" : "00:00:00.250",
"value" : "19.2",
"flag" : "0"
}, {
"date" : "2013-08-01",
"time" : "00:00:00.250",
"value" : "18.1",
"flag" : "0"
}, {
"date" : "2013-09-01",
"time" : "00:00:00.250",
"value" : "14.4",
"flag" : "0"
}, {
"date" : "2013-10-01",
"time" : "00:00:00.250",
"value" : "12.2",
"flag" : "0"
}, {
"date" : "2013-11-01",
"time" : "00:00:00.250",
"value" : "6.7",
"flag" : "0"
}, {
"date" : "2013-12-01",
"time" : "00:00:00.250",
"value" : "5.9",
"flag" : "0"
}, {
"date" : "2014-01-01",
"time" : "00:00:00.250",
"value" : "5.7",
"flag" : "0"
} ]
}]
}
Example TimeSteps.xml using OGC compliant periods
The following is an example of the TimeSteps.xml from the RegionConfig folder. For example to search for time series with a 3 hourly time step, the parameter timeStepId=PT3H can be added to the request.
<?xml version="1.0" encoding="UTF-8"?>
<timeSteps xmlns="http://www.wldelft.nl/fews" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.wldelft.nl/fews http://fews.wldelft.nl/schemas/version1.0/timeSteps.xsd">
<!--
Configure well known timesteps as [ISO 8601:1988(E)] standards.
See also:
http://cite.opengeospatial.org/OGCTestData/wms/1.1.1/spec/wms1.1.1.html#date_time.time
-->
<!-- Yearly time steps -->
<timeStep id="P1Y" multiplier="1" unit="year"/>
<!-- Monthly time steps -->
<timeStep id="P1M" multiplier="1" unit="month"/>
<!-- Daily time steps -->
<timeStep id="PT1D" multiplier="1" unit="day"/>
<timeStep id="PT5D" multiplier="5" unit="day"/>
<!-- Hourly time steps -->
<timeStep id="PT1H" multiplier="1" unit="hour"/>
<timeStep id="PT2H" multiplier="2" unit="hour"/>
<timeStep id="PT3H" multiplier="3" unit="hour"/>
<timeStep id="PT6H" multiplier="6" unit="hour"/>
<!-- Minute based time steps -->
<timeStep id="PT1M" multiplier="1" unit="minute"/>
<timeStep id="PT5M" multiplier="5" unit="minute"/>
<timeStep id="PT10M" multiplier="10" unit="minute"/>
<timeStep id="PT15M" multiplier="15" unit="minute"/>
<timeStep id="PT30M" multiplier="30" unit="minute"/>
<timeStep id="PT60M" multiplier="60" unit="minute"/>
<!-- Second based time steps -->
<timeStep id="PT1S" multiplier="1" unit="second"/>
<timeStep id="PT5S" multiplier="5" unit="second"/>
</timeSteps>
GET timeseries/displaygroups (2019.02)
Returns a pi timeseries xml or json file containing the timeseries data filtered by a plotId of the DisplayGroups.xml configuration in the SystemConfigFiles folder. See also http://fews.wldelft.nl/schemas/version1.0/displayGroups.xsd.
The TimeSeriesSets configured for a plotId will be used to filter the timeSeries. The line, area and bar elements are used when determining the relevant TimeSeriesSets. In case of forecasts, this means only the current forecast will be retrieved. It is not possible to request older forecasts.
If no line, area or bar elements is used in the displayGroups.xml configuraiton, the TimeSeriesSets will not be applied.
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
- documentFormat (string): PI_XML (default) or PI_JSON
- endTime (dateTime: yyyy-MM-ddTHH:mm:ssZ): End time of search period that looks for timeseries values that lie within this period.
- locationIds (string): Subset of locations for which to retrieve timeseries. This parameter can be duplicated to use multiple locationIds. At least one location id is required.
- 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)
- onlyManualEdits (boolean): Toggle to return only manual edits.
plotId (string, required): the plotId as configured in the DisplayGroups.xml for which the configured TimeSeriesSets will be determined from the line, area and bar elements.
- showProducts (boolean): Toggle to display product information that is assigned to a forecast. (Since 2019.02).
- showStatistics (boolean): Toggle to return statistics information about timeseries. Typically used in combination with onlyHeaders. Returns additional information about data availability of timeseries (Since 2015.01).
- firstValueTime: First time with a value in the timeSeries
- lastValueTime: Last time with a value in the timeSeries
- maxValue: Maximum value in the timeSeries
- minValue: Minimum value in the timeSeries
- valueCount: Number of values in the timeSeries
- showThresholds (boolean): Option to toggle the returning of threshold information in the headers
- showEnsembleMemberIds (boolean): Show ensemble member ids.
- thinning (long): Thinning is used to retrieve the visually interesting time steps of a timeSeries. It tries to keep the peaks and gaps and minimizes the number of time steps that have to be retrieved. It is typically used for visualizations. The value to be specified should be equal to the view period of the timeSeries that is visualized divided by the number of pixels that are available for display. For example: visualizing a view period of 5 years (157784760000 milliseconds) on a display of 1024, the thinning parameter should be set to 157784760000/1024 = 15408668. (Since 2019.02)
- useMilliseconds (boolean) Optional argument. Default is false. If it is set to true, the response will contain milliseconds. See example below
- startTime (dateTime: yyyy-MM-ddTHH:mm:ssZ): Start time of search period that looks for timeseries values that lie within this period.
- useDisplayUnits (boolean): Export values using display units.
Response
- Timeseries PI-XML or PI-JSON file content..
Example request
curl "http://localhost:8080/FewsWebServices/rest/fewspiservice/v1/timeseries/displaygroups?plotId=TidalForecasts&locationIds=UKCFF_ABD&startTime=2019-06-10T00:00:00Z&endTime=2019-06-25T00:00:00Z"
Example PI-XML and JSON response
See the timeseries endpoint for examples.
GET timeseries/grid (2018.02)
The timeseries/grid endpoint is intended to be used together with the Delf-FEWS WMS service. Every layer that is provided by the WMS service, can be used with this endpoint. See also FEWS Web Mapping Service with time support (WMS-T).
Returns a pi timeseries xml file containing the timeseries data from a grid cell for a request period. The grid is specified by passing a layerId. The grid cell is determined by specifying a x and y coordinate and a bounding box. Currenly only EPSG:3857 is supported for the x,y, and bounding box coordinates. At least a layer, startTime, endTime, x,y and bounding box are required.
Request parameters
- bbox (string): bounding box of map that is viewed in , separated EPSG:3857 format. The order of the coordinates is as follows: bottom left X, bottom left Y, top right X, top right Y. For example:
bbox=-1558755.612890017,4979850.04379049,1623657.8112034467,6709422.556884765 - 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
- documentFormat (string): PI_XML (default) or PI_JSON
- elevation (double): used for 3d data, like for example water depth, to get the timeseries of a grid point at a specific elevation. Since 2020.01.
- endTime (dateTime: yyyy-MM-ddTHH:mm:ssZ, required): End time of search period that looks for timeseries values that lie within this period.
- externalForecastTime (dateTime format: yyyy-MM-ddTHH:mm:ssZ): Time value of external forecast time.
- ensembleId (String): Used in combination with ensembleMemberId to identify a unique ensemble. Since 2020.01.
- ensembleMemberId (String): Used in combination with ensembleId to identify a unique ensemble. Since 2020.01.
- importFromExternalDataSource (boolean, default true): import data from external data source (Archive). since 2019.02.
- layers (string, required): layerd id (only one layer is supported and required) that matches the gridPlot id as configured in the gridDisplay. Every gridPlot that has been configured in the grid display configuration represents a WMS layer. For more information, see the WMS Service documentation: FEWS Web Mapping Service with time support (WMS-T)
- 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
- onlyManualEdits (boolean): Toggle to return only manual edits.
- showProducts (boolean): Toggle to display product information that is assigned to a forecast. (Since 2019.02). See below for an example.
- showStatistics (boolean): Toggle to return statistics information about timeseries. Typically used in combination with onlyHeaders. Returns additional information about data availability of timeseries (Since 2015.01).
- firstValueTime: First time with a value in the timeSeries
- lastValueTime: Last time with a value in the timeSeries
- maxValue: Maximum value in the timeSeries
- minValue: Minimum value in the timeSeries
- valueCount: Number of values in the timeSeries
- showThresholds (boolean): Option to toggle the returning of threshold information in the headers
- showEnsembleMemberIds (boolean): Show ensemble member ids.
- showVerticalProfile (boolean): Show vertical profile in case of 3D data. Since 2020.01.
- startTime (dateTime: yyyy-MM-ddTHH:mm:ssZ, required): Start time of search period that looks for timeseries values that lie within this period.
- thinning (long): unit ms/pixel. Thinning is used to retrieve the visually interesting time steps of timeSeries. It tries to keep the peaks and gaps and minimizes the number of time steps that have to be retrieved. It is typically used for visualizations. The value to be specified should be equal to the view period in milliseconds of the timeSeries that is visualized divided by the number of pixels that are available for display. For example: visualizing a view period of 5 years (157784760000 milliseconds) on a display of 1024 pixels, the thinning parameter should be set to 157784760000/1024 = 15408668. (Since 2019.02)
- useMilliseconds (boolean) Optional argument. Default is false. If it is set to true, the response will contain milliseconds. See example below. Since 2019.02
- useDisplayUnits (boolean): Export values using display units.
- x (double, required): x postion on the map in EPSG:3857 format.
- y (double, required): y postion on the map in EPSG:3857 format.
Response
- Timeseries PI-XML or PI-JSON file content.
Example request
curl "http://localhost:8080/FewsWebServices/rest/fewspiservice/v1/timeseries/grid?documentFormat=PI_JSON&layers=Temp_forecast_nwp&x=-121480.85450867479&y=6072939.872066073&startTime=2020-01-08T01:00:00.000Z&endTime=2020-01- 08T01:00:00.000Z&bbox=-1558755.612890017,4979850.04379049,1623657.8112034467,6709422.556884765"
WMS Test page
This timeSeries grid functionality can also be tested using the WMS service test page. Right clicking on a grid cell, will show a popup that will show the value of the grid cell for the current time step. When clicking on the PI Service URL the PI Request that was used to determine the current value, will be opened.
Example PI-XML and JSON response
See the timeseries endpoint for examples.
3D grids elevation and vertical profiles
For 3D grids the elevation parameter can be used to get the timeseries of a grid cell at a specified elevation (for example to get the water temperature at a specific water depth). On the WMS testing page this functionality can be tested by right clicking on a grid cell. The vertical slider on the left can be used to specify the elevation that should be used. When selecting the "Grid time series" option, a popup with the PI service URL will be generated that will get the timeseries for a grid cell at the selected elevation.
An example request with elevation:
http://localhost:8080/FewsWebServices/rest/fewspiservice/v1/timeseries/grid?documentFormat=PI_JSON&layers=kzn_temperature&x=3496535.421877103&y=-3484305.4973514746&startTime=2010-04-15T00:00:00.000Z&endTime=2010-04-15T00:00:00.000Z&bbox=3272727.803058107,-3739299.4237108226,3835304.3312370046,-3372401.6879419754&_=1602068760367&importFromExternalDataSource=false&elevation=10.453057
3D grids elevation and vertical profiles
It is also possible to get a vertical profile for 3D data. On the WMS testing page this functionality can be tested by right clicking on a grid cell. When selecting the "Vertical Profile" option, a popup with the PI service URL will be generated that will get the timeseries of all elevations for a grid cell at the selected timestep. This is achieved by passing the showVerticalProfile=true parameter. It is possible to request vertical profiles for more than one time step by using the startTime and endTime.
An example request to get the vertical profile for one time step:
http://localhost:8080/FewsWebServices/rest/fewspiservice/v1/timeseries/grid?documentFormat=PI_JSON&layers=kzn_temperature&x=3516714.7973443894&y=-3506319.361497606&startTime=2010-04-15T00:00:00.000Z&endTime=2010-04-15T00:00:00.000Z&bbox=3272727.803058107,-3739299.4237108226,3835304.3312370046,-3372401.6879419754&_=1602068935896&importFromExternalDataSource=false&showVerticalProfile=true
The PI response of profiles will contain domain axes. In this example the water_depth is the domain axis and the different elevations are reported in the domainAxisValues.
Typical profile PI_JSON response
{
"version" : "1.28",
"timeZone" : "0.0",
"timeSeries" : [ {
"header" : {
"type" : "instantaneous",
"moduleInstanceId" : "kzn",
"locationId" : "kzn",
"parameterId" : "water_temperature",
"timeStep" : {
"unit" : "nonequidistant"
},
"startDate" : {
"date" : "2010-04-15",
"time" : "00:00:00"
},
"endDate" : {
"date" : "2010-04-15",
"time" : "00:00:00"
},
"forecastDate" : {
"date" : "2019-10-10",
"time" : "18:00:00"
},
"missVal" : "-999.0",
"stationName" : "kzn",
"units" : "degrees",
"domainAxis" : [ {
"parameterId" : "water_depth",
"units" : "m"
} ],
"creationDate" : "2020-06-24",
"creationTime" : "06:19:05",
"approvedDate" : {
"date" : "2020-06-24",
"time" : "06:19:09"
}
},
"domains" : [ {
"domainAxisValues" : [ {
"parameterId" : "water_depth",
"values" : [ [ "36.49779" ], [ "109.4925" ], [ "182.48721" ], [ "255.48279" ], [ "328.4775" ], [ "401.4722" ], [ "474.4678" ], [ "547.4625" ], [ "620.4572" ], [ "693.4528" ], [ "766.4475" ], [ "839.4422" ] ]
} ],
"events" : [ {
"date" : "2010-04-15",
"time" : "00:00:00",
"flag" : "2",
"values" : [ [ "26.1" ], [ "21.0" ], [ "17.7" ], [ "15.2" ], [ "13.3" ], [ "11.7" ], [ "10.6" ], [ "10.0" ], [ "9.5" ], [ "8.8" ], [ "8.1" ], [ "7.4" ] ]
} ]
} ]
} ]
}
GET archive/parameters (2020.01)
Returns a list of parameters that are available in the archive. Optionally the parameters can be filtered by one or more location ids or archive attributes.
Request parameters
- locationIds (string): Subset of locations for which to retrieve parameters. This parameter has to be duplicated to specify multiple locations.
- attribute(key)=value (string): on ore more attributes that have to match the archive attribute. Attributes are passed by passing the key as an argument to the attribute() paramteter and the value as parameter value. See the example where only locations will be returned when an archive attribute storageId was set with the value storageA.
- documentVersion (string, 1.9 or up): File format version (optional). For example: 1.23
- documentFormat (string): PI_XML (default) or PI_JSON
Example query
http://localhost:8080/FewsWebServices/rest/fewspiservice/v1/archive/parameters?attribute(storageId)=storageA
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.9">
<parameter id="QR_Adj">
<name>QR_Adj</name>
<parameterType>instantaneous</parameterType>
<unit></unit>
</parameter>
</timeseriesparameters>
GET archive/locations (2020.01)
Returns a list of locations that are available in the archive. Optionally the locations can be filtered by one or more parameter ids or archive attributes.
Request parameters
- parameterIds (string): Subset of parameters for which to retrieve locations. This parameter has to be duplicated to specify multiple parameters.
- attribute(key)=value (string): on ore more attributes that have to match the archive attribute. Attributes are passed by passing the key as an argument to the attribute() paramteter and the value as parameter value. See the example where only locations will be returned when an archive attribute storageId was set with the value storageA.
- documentVersion (string, 1.9 or up): File format version (optional). For example: 1.23
- documentFormat (string): PI_XML (default) or PI_JSON
Example query
http://localhost:8080/FewsWebServices/rest/fewspiservice/v1/archive/locations?attribute(storageId)=storageA
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.9">
<geoDatum>LOCAL</geoDatum>
<location locationId="BCRA1">
<shortName>Bear Creek Dam</shortName>
<lat>34.399166107177734</lat>
<lon>-87.98777770996094</lon>
</location>
</Locations>
GET archive/attributes (2020.01)
Returns a list of attributes with their values that are available in the archive. Optionally the attributes can be filtered by one or more attribute keys, one or more parameter ids or one or more location ids.
Request parameters
- parameterIds (string): Subset of parameters for which to retrieve locations. This parameter has to be duplicated to specify multiple parameters. (not available yet)
- locationIds (string): Subset of locations for which to retrieve parameters. This parameter has to be duplicated to specify multiple locations. (not available yet)
- attributes (string): Subset of archive attribute keys. Only attributes with this key will be returned. This parameter has to be duplicated to specify multiple attributes. This parameter is usefull to get all values for a specific attribute.
- documentVersion (string, 1.9 or up): File format version (optional). For example: 1.23
- documentFormat (string): PI_XML (default) or PI_JSON
Example query
http://localhost:8080/FewsWebServices/rest/fewspiservice/v1/archive/attributes?attributes=storageId
Example response:
<?xml version="1.0" encoding="UTF-8"?>
<archiveAttributes 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_archive_attributes.xsd">
<attribute>
<key>storageId</key>
<value>storageA</value>
</attribute>
</archiveAttributes>
GET archive/netcdfstorageforecasts
Returns a list of forecasts from the external netcdf storage from the archive.
Request parameters
- startTime (dateTime: yyyy-MM-ddTHH:mm:ssZ): Start time of the archive search period
- attribute(key)=value (string): on ore more attributes that have to match the archive attribute. Attributes are passed by passing the key as an argument to the attribute() paramteter and the value as parameter value. See the example where only forecasts will be returned were the long_name is equal to parameterA
- endTime (dateTime: yyyy-MM-ddTHH:mm:ssZ): End time of the archive search period
- requestedAttribute(string): The attributes of the forecast which should be included in the response
- forecastCount (integer): The maximum number of forecasts to be returned from archive. If you only want to download the most recent forecast in the requested period then use forecastCount=1
documentFormat (string): PI_XML (default) or PI_JSON
Example query
http://localhost:8080/FewsWebServices/rest/fewspiservice/v1/archive/netcdfstorageforecasts?attribute(long_name)=parameterA&requestedAttribute=long_name&startTime=2019-01-01T00:00:00Z&endTime=2020-01-01T00:00:00Z&documentFormat=PI_JSON
Example response
{
"externalNetCDFStorageForecasts" : [ {
"forecastTime" : "2019-09-27T12:00:00+0000",
"forecastAvailableTime" : "2020-06-23T13:45:53+0000",
"attributes" : [ {
"key" : "long_name",
"value" : "sep"
}, {
"key" : "source",
"value" : "Export NETCDF-CF_GRID_MATROOS from Delft-FEWS"
}, {
"key" : "source",
"value" : "RWsOS-Noordzee"
} ]
}, {
"forecastTime" : "2019-09-27T06:00:00+0000",
"forecastAvailableTime" : "2020-06-23T13:45:53+0000",
"attributes" : [ {
"key" : "long_name",
"value" : "sep"
}, {
"key" : "source",
"value" : "Export NETCDF-CF_GRID_MATROOS from Delft-FEWS"
}, {
"key" : "source",
"value" : "RWsOS-Noordzee"
} ]
} ]
}
GET archive/products (2019.02)
Returns a zip-file with the requested products from the archive.
Request parameters
- areaId (string): the area id of the requested products
- sourceId (string): the source id of the requested products
- startTime (dateTime: yyyy-MM-ddTHH:mm:ssZ): Start time of the archive search period
- endTime (dateTime: yyyy-MM-ddTHH:mm:ssZ): End time of the archive search period
- productCount (integer): the maximum number of products to be returned from the archive. If you only the download the most recent product in the requested period then use productCount=1
http://localhost:8080/FewsWebServices/rest/fewspiservice/v1/archive/products?areaId=myAreaId&sourceId=mySourceId&startTime=2011-10-10T12:00:00Z&endTime=2021-10-10T12:00:00Z&productCount=1
POST timeseries (2017.02)
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.
As far as writing timeseries is concerned, the timeseries you post to the rest service should match one of the time series sets in the default filter or one of its sub filters. To make sure you only write time series for a specific filter, you can pass a filterId with the POST request. Only timeseries that have timeseries sets that are configured in that filter (or one of its sub filters) will be accepted. If no filterId is used, all time series will be accepted that are configured in the default filter. Writing the time series works similar to importing time series using the pi.xml format using the "PI" import type. See also: Delft-Fews Published Interface timeseries Format (PI) Import
In case a time series already exists in the database, the time series will be overwritten by the ones that are posted. For forecast time series with different forecastDates a new time series will be added. The latter can be achieved by providing a forecastDate element in the POST request, e.g. <forecastDate date="2013-01-01" time="00:00:00"/>.
N.B.: by default POST operations are disabled in the Delft-FEWS WebServices and have to be explicitly enabled by setting the READONLY_MODE to false in the FewsPiService.properties. See also: FEWS Web Services configuration FewsPiService.properties.
Request parameters
filterId (string, optional): 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. When no filterId is specified, the default filter applies.
convertDatum (boolean, optional): Convert values from relative location height to absolute height values
Body parameters
piTimeSeriesXmlContent (xml string, required): PiTimeseries xml file encoded in the 'application/x-www-form-urlencoded Content-Type. Example of a piTimeSeriesXmlContent (unencoded):
<?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>
Since 2018.02 the service also supports milliseconds. The parser automatically recognises which format is used.
<?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.750"/> <endDate date="2013-01-01" time="00:50:00.250"/> <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.750" value="13.0" flag="0"/> <event date="2013-01-01" time="00:50:00.250" value="13.0" flag="0"/> </series> </TimeSeries>
N.B. The SOAP Web Service has support for posting timeSeries as binary data using the piTimeSeriesBinaryContent. This is NOT support in this REST service of the PI Service.
- When sending in a set of timeseries that correspond to (e.g.) a completed forecast over multiple locations, it is not necessary to POST each location separately, the entire set be sent in one TimeSeries XML document with multiple series.
- There is no option in the REST Web Service to do any aggregation or transformation.
Response
- Diag PI 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/" -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>
Example response with non-matching time series.
It is possible that the posted time series do not match any of the time series sets that have been configured in the default filter or in a passed filterId. In that case, the response will report that some time series couldn't be mapped. In the following eexample 8 time series were posted, but only one time series was actually writte, 7 time series were rejected:
<?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="3" description="Import.Info: External time series successfully mapped to FEWS time series amerongen_beneden H.voorspeld (m) 10 minutes Tue Jan 01 01:00:00 CET 2013 z=0.0"/>
<line level="3" description="Import.Info: 1 time series imported, 7 time series rejected"/>
<line level="3" description="Import.Info: The following locations-parameter combination imported amerongen_beneden:H.voorspeld"/>
</Diag>
Example forecast time series.
By specifying a forecastDate it is possible to write external forecasts using the PI service.
<?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>amerongen_beneden</locationId>
<parameterId>H.voorspeld</parameterId>
<timeStep unit="minute" multiplier="10"/>
<startDate date="2013-01-01" time="00:00:00"/>
<endDate date="2013-01-01" time="00:30:00"/>
<forecastDate date="2013-01-01" time="00:00:00"/>
<missVal>-999.0</missVal>
<units>m</units>
</header>
<event date="2013-01-01" time="00:00:00" value="10.0" flag="0" />
<event date="2013-01-01" time="00:10:00" value="12.0" flag="0"/>
<event date="2013-01-01" time="00:20:00" value="11.8" flag="0"/>
<event date="2013-01-01" time="00:30:00" value="9.0" flag="0"/>
</series>
</TimeSeries>
Example code
To post timeSeries to the Delft-FEWS WebServices, the following is example JAVA code:
String piTimeSeries = "PI XML Content";
URL url = new URL("http://localhost:8080/FewsWebServices/rest/fewspiservice/v1/timeseries");
HttpURLConnection connection = (HttpURLConnection) url.openConnection();
connection.setDoInput(true);
connection.setRequestMethod("POST");
connection.setDoOutput(true);
connection.setRequestProperty("Content-Type", "application/x-www-form-urlencoded");
connection.setRequestProperty("charset", "utf-8");
String postData = "piTimeSeriesXmlContent=" + URLEncoder.encode(piTimeSeries, StandardCharsets.UTF_8);
connection.setRequestProperty("Content-Length", Integer.toString(postData.length()));
connection.setUseCaches(false);
try (DataOutputStream wr = new DataOutputStream(connection.getOutputStream())) {
wr.write(postData.getBytes());
}
GET taskruns
Get the taskRuns that comply to the filters.
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.
- taskRunStatusIds (string): Filter taskruns using the taskrunstatus code value. For valid status codes see the section 'Get taskrunstatus' below.
documentVersion (string, 1.9 or up): File format version (optional). For example: 1.23
Response
- TaskRuns PI 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 (2017.02)
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 successfulnull= No status available (produces when method call times-out)
Example request
curl "localhost:8080/FewsWebServices/rest/fewspiservice/v1/taskrunstatus?taskId=1_0"
Example response
C
POST runtask (2017.02)
Runs a workflow task for a given workflowId. Returns a handle to the task in the form of a taskid. This taskId can be used to track the status of the workflow using the taskrunstatus method. Since 2018.02 it is possible to use a workflow descriptor attribute: waitWhenAlreadyRunning. This will allow running a task that hasn't been scheduled to wait when another task of that workflow is already running.
Request parameters
- workflowId (string, required): Identifier of the task to run
- startTime (dateTime: yyyy-MM-ddTHH:mm:ssZ): Start of run period. Used for state selection period.
- timeZero (dateTime: yyyy-MM-ddTHH:mm:ssZ): Forecast time zero. If missing System time is used (optional)
- endTime (dateTime: yyyy-MM-ddTHH:mm:ssZ): 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
- piModelParametersXmlContent (pi XML 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 encoded in the 'application/x-www-form-urlencoded Content-Type.
Response
- taskId String with the identifier of the task that is run.
Example request
curl "http://localhost:8080/FewsWebServices/rest/fewspiservice/v1/runtask/?workflowId=ImportObserved&startTime=2014-01-01T00:00:00Z+0000&timeZero=2014-01-01T00:00:00Z+0000&endTime=2014-01-01T00:30:00Z+0000" -X POST -H "Content-Type: application/x-www-form-urlencoded" -d ""
Example response
1_0
GET timeseriesmodifiers (2017.02)
Get a list of all timeSeries modifiers
Request parameters
locationIds (string):
moduleInstanceIds (string):
startTime (dateTime: yyyy-MM-ddTHH:mm:ssZ): start time of modifiers search period
endTime (dateTime: yyyy-MM-ddTHH:mm:ssZ): end time of modifiers search period.
userId (string):
modifierTypeId (string):
active (boolean, default true):
userDefinedModifierDescriptionKeyValuePair (string):
If no startTime and endTime are given, the search period is any time.
Response
- timeSeriesModifiers PI XML
Example request
curl "http://localhost:8080/FewsWebServices/rest/fewspiservice/v1/timeseriesmodifiers"
Example response
<?xml version="1.0" encoding="UTF-8"?>
<Modifiers 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_modifiers.xsd">
<modifier>
<name>T.obs.mean_DE BILT</name>
<modifierId>0</modifierId>
<systemActivityDescriptorId>34</systemActivityDescriptorId>
<enabled>true</enabled>
<modifierType>MISSING_VALUE_MODIFIER</modifierType>
<userId>Andre Grijze</userId>
<startTime date="1900-10-17" time="00:00:00"/>
<endTime date="2017-11-23" time="00:00:00"/>
<validTime date="3000-01-01" time="00:00:00"/>
<creationTime date="2017-10-24" time="11:43:11"/>
<constantValueTimeSeriesModifier>
<timeSeriesSet>
<moduleInstanceId>ImportObserved</moduleInstanceId>
<parameterId>T.obs.mean</parameterId>
<locationId>63306260000</locationId>
<timeSeriesType>external historical</timeSeriesType>
<timeStep unit="nonequidistant"/>
<ensembleId>main</ensembleId>
</timeSeriesSet>
<startTime date="1900-10-17" time="00:00:00"/>
<endTime date="2017-11-23" time="00:00:00"/>
<value>NaN</value>
</constantValueTimeSeriesModifier>
</modifier>
</Modifiers>
GET modifiers
Get a list of all modifiers.
Request parameters
startTime (dateTime: yyyy-MM-ddTHH:mm:ssZ): start time of modifiers search period
endTime (dateTime: yyyy-MM-ddTHH:mm:ssZ): end time of modifiers search period.
modifierTypeId (string): filter on modifiers by modifierTypeId as specified in the ModifierTypes.xml configuration. If modifier type cannot be found, not filtering on type is done.
If no startTime and endTime are given, the search period is any time.
Response
- Modifiers PI XML
Example request
curl "http://localhost:8080/FewsWebServices/rest/fewspiservice/v1/modifiers?modifierTypeId=MISSING_VALUE_MODIFIER"
Example response
<?xml version="1.0" encoding="UTF-8"?>
<Modifiers 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_modifiers.xsd">
<modifier>
<name>T.obs.mean_DE BILT</name>
<modifierId>0</modifierId>
<systemActivityDescriptorId>34</systemActivityDescriptorId>
<enabled>true</enabled>
<modifierType>MISSING_VALUE_MODIFIER</modifierType>
<userId>Rudie Ekkelenkamp</userId>
<startTime date="1900-10-17" time="00:00:00"/>
<endTime date="2017-11-23" time="00:00:00"/>
<validTime date="3000-01-01" time="00:00:00"/>
<creationTime date="2017-10-24" time="11:43:11"/>
<constantValueTimeSeriesModifier>
<timeSeriesSet>
<moduleInstanceId>ImportObserved</moduleInstanceId>
<parameterId>T.obs.mean</parameterId>
<locationId>63306260000</locationId>
<timeSeriesType>external historical</timeSeriesType>
<timeStep unit="nonequidistant"/>
<ensembleId>main</ensembleId>
</timeSeriesSet>
<startTime date="1900-10-17" time="00:00:00"/>
<endTime date="2017-11-23" time="00:00:00"/>
<value>NaN</value>
</constantValueTimeSeriesModifier>
</modifier>
</Modifiers>
POST modifiers (2017.02)
Create new modifiers.
Request parameters
commitModiifers (boolean): Indicates if the modifiers should be committed after the uploaded. This option defaults to true.
deleteAllModifiers (boolean): Indicates if all the existing modifiers should be deleted prior to inserting the new modifiers. This option defaults to false.
Body parameters
- piModifiersXmlContent (pi Modifiers XML url encoded): Contents of a modifiers file. The xml file content has to be encoded in the 'application/x-www-form-urlencoded Content-Type.
Response
- Diag PI xml response with all diagnostic output.
Example request
curl "http://localhost:8080/FewsWebServices/rest/fewspiservice/v1/modifiers" -X POST -H "Content-Type: application/x-www-form-urlencoded" -d "piModifiersXmlContent="%3C%3Fxml%20version%3D%221.0%22%20encoding%3D%22UTF-8%22%3F%3E%0D%0A%3CModifiers%20xmlns%3Axsi%3D%22http%3A%2F%2Fwww.w3.org%2F2001%2FXMLSchema-instance%22%20xmlns%3D%22http%3A%2F%2Fwww.wldelft.nl%2Ffews%2FPI%22%20xsi%3AschemaLocation%3D%22http%3A%2F%2Fwww.wldelft.nl%2Ffews%2FPI%20http%3A%2F%2Ffews.wldelft.nl%2Fschemas%2Fversion1.0%2Fpi-schemas%2Fpi_modifiers.xsd%22%3E%0D%0A%20%20%20%20%3Cmodifier%3E%0D%0A%20%20%20%20%20%20%20%20%3Cname%3ET.obs.mean_DE%20BILT%3C%2Fname%3E%0D%0A%20%20%20%20%20%20%20%20%3Cenabled%3Etrue%3C%2Fenabled%3E%0D%0A%20%20%20%20%20%20%20%20%3CmodifierType%3EMODIFY_TIMESERIES%3C%2FmodifierType%3E%0D%0A%20%20%20%20%20%20%20%20%3CuserId%3ERudie%20Ekkelenkamp%3C%2FuserId%3E%0D%0A%20%20%20%20%20%20%20%20%3CstartTime%20date%3D%221900-10-24%22%20time%3D%2200%3A00%3A00%22%2F%3E%0D%0A%20%20%20%20%20%20%20%20%3CendTime%20date%3D%222017-10-25%22%20time%3D%2200%3A00%3A00%22%2F%3E%0D%0A%20%20%20%20%20%20%20%20%3CvalidTime%20date%3D%222017-10-24%22%20time%3D%2200%3A00%3A00%22%2F%3E%0D%0A%20%20%20%20%20%20%20%20%3CcreationTime%20date%3D%222017-10-24%22%20time%3D%2211%3A15%3A43%22%2F%3E%0D%0A%20%20%20%20%20%20%20%20%3CtransformationTimeSeriesModifier%3E%0D%0A%20%20%20%20%20%20%20%20%20%20%20%20%3CtimeSeriesSet%3E%0D%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%3CmoduleInstanceId%3EImportObserved%3C%2FmoduleInstanceId%3E%0D%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%3CparameterId%3ET.obs.mean%3C%2FparameterId%3E%0D%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%3ClocationId%3E63306260000%3C%2FlocationId%3E%0D%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%3CtimeSeriesType%3Eexternal%20historical%3C%2FtimeSeriesType%3E%0D%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%3CtimeStep%20unit%3D%22nonequidistant%22%2F%3E%0D%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%3CensembleId%3Emain%3C%2FensembleId%3E%0D%0A%20%20%20%20%20%20%20%20%20%20%20%20%3C%2FtimeSeriesSet%3E%0D%0A%20%20%20%20%20%20%20%20%20%20%20%20%3Cmultiplier%3E1.0%3C%2Fmultiplier%3E%0D%0A%20%20%20%20%20%20%20%20%20%20%20%20%3Cdivider%3E1.1%3C%2Fdivider%3E%0D%0A%20%20%20%20%20%20%20%20%20%20%20%20%3Cincrementer%3E0.0%3C%2Fincrementer%3E%0D%0A%20%20%20%20%20%20%20%20%20%20%20%20%3Cdelay%3E0%3C%2Fdelay%3E%0D%0A%20%20%20%20%20%20%20%20%3C%2FtransformationTimeSeriesModifier%3E%0D%0A%20%20%20%20%3C%2Fmodifier%3E%0D%0A%3C%2FModifiers%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="3" description="Successfully imported modifier:none MODIFY_TIMESERIES -1 T.obs.mean_DE BILT none"/>
</Diag>
GET workflows (2017.02)
Request parameters
- documentVersion (string, 1.9 or up): File format version (optional). For example: 1.23
Response
- xml workflows.
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 (2017.02)
Request parameters
- documentVersion (string, 1.21 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 samples. Note: creation time of samples is actually the creation time of the task that produced/imported these samples.
- endTime (dateTime: yyyy-MM-ddTHH:mm:ssZ): End time of search period that looks for sample values that lie within this period.
- filterId (string): Filter id.
- locationIds (string): Subset of locations for which to retrieve samples. Repeat parameter for multiple location ids.
- omitMissing (boolean): Toggle omitting or returning of missing values in response
- onlyHeaders (boolean): Toggle to return only header information or also data
- parameterIds (string): Subset of parameters for which to retrieve samples.
- qualifierIds (string): Subset of qualifiers for which to retrieve samples.
- sampleIds Subset of sample id's for which to retrieve samples. Repeat parameter for multiple samples ids.
- startCreationTime (dateTime: yyyy-MM-ddTHH:mm:ssZ): Start time of search period that looks for creation time of samples. Note: creation time of samples is actually the creation time of the task that produced/imported these samples.
- startTime (dateTime: yyyy-MM-ddTHH:mm:ssZ): Start time of search period that looks for sample values that lie within this period.
Since all parameters are optional, some defaults are chosen for the search period in case no search period or creation period was specified. The following rules apply:
- If no startCreationTime and endCreationTime have been set, the startTime and endTime are used to determine the search period.
- If no startTime and endTime have been specified, the search period will be set to the current system time minus one day and one hour until the current system time plus one day and one hour.
Response
- Samples PI XML file content
Example request
curl "http://localhost:8080/FewsWebServices/rest/fewspiservice/v1/samples?sampleIds=713&locationIds=MBP012&startTime=1970-01-01T00:00:00Z+0000&endTime=2017-01-01T00:00:00Z+0000"
Example response
<?xml version="1.0" encoding="UTF-8"?>
<Samples 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_samples.xsd" version="1.23" xmlns:fs="http://www.wldelft.nl/fews/fs" xmlns:qualifierId="http://www.wldelft.nl/fews/qualifierId">
<timeZone>0.0</timeZone>
<sample id="713">
<header>
<locationId>MBP012</locationId>
<sampleDate date="1980-12-31" time="23:00:00"/>
<lat>52.18084820135932</lat>
<lon>5.083729510982581</lon>
<x>134244.0</x>
<y>465900.0</y>
</header>
<properties>
<string key="externereferentie" value="PUT-01\SYS\0000000713"/>
<string key="xcoormonster" value="134240"/>
<string key="ycoormonster" value="465900"/>
<string key="monsternemer" value="IMP"/>
<string key="analist" value="IMP"/>
<string key="bron" value="TABHIST"/>
</properties>
<table>
<row parameterId="PTB_Tans" qualifierId:q1="AC_6" qualifierId:q2="AP_22" qualifierId:q3="TWN_3623" qualifierId:q4="CO6" qualifierId:q5="EE_22" qualifierId:q6="GH_3" qualifierId:q7="WM_1" flag="0" value="8.0" unit="-"/>
<row parameterId="PTB_Tans" qualifierId:q1="AC_6" qualifierId:q2="AP_22" qualifierId:q3="TWN_2319" qualifierId:q4="CO6" qualifierId:q5="EE_22" qualifierId:q6="GH_3" qualifierId:q7="WM_1" flag="0" value="1.0" unit="-"/>
</table>
</sample>
</Samples>
GET processdata (2017.02)
Request parameters
startTime (dateTime: yyyy-MM-ddTHH:mm:ssZ): start time of the requested period
endTime (dateTime: yyyy-MM-ddTHH:mm:ssZ): end time of the requested period
workflowId (string): workflow which should be run. This workflow should generate the requested data file
xMin (string): left x coordinate of the bounding box for which data should be generated
xMax (string): right x coordinate of the bounding box for which data should be generated
yMin (string): lower y coordinate of the bounding box for which data should be generated
yMax (string): upper y coordinate of the bounding box for which data should be generated
xCellSize (string): width of the cell size
yCellSize (string): height of the cell size
Response
- The workflow indicated by the workflowId should generate a data-file (usually a netcdf-file). if the workfow has succesfully generated a netcdf-file, the response will be binary stream containing the generated file. If no file is generated an 500 error will be thrown.
Example request
curl "http://localhost:8080/FewsWebServices/rest/fewspiservice/v1/processdata/?workflowId=Transformation_ASA_Grid_Wind&xMin=52.58&yMin=24.38&xMax=54.62&yMax=26.10&xCellSize=0.01&yCellSize=0.01&startTime=2017-11-18T00:00:00Z&endTime=2017-11-19T00:00:00Z"
Configuration
A property EXPORT_FOLDER_PROCESS_DATA should be configured in the global properties or in the webservice properties. The workflow indicated by the workflow id should export data to a folder EXPORT_FOLDER_PROCESS_DATA.
GET qualifiers (2019.02)
Retrieve all configured qualifiers.
Request parameters
- documentFormat (string): only PI_XML is supported.
- showAttributes (boolean): toggle to show qualifier attributes. Default is false.
Response
- Qualifiers in PI-XML.
Example request
curl "http://localhost:8080/FewsWebServices/rest/fewspiservice/v1/locations?showAttributes=true&documentVersion=1.24"
Example PI-XML response
<?xml version="1.0" encoding="UTF-8"?>
<qualifiers 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_qualifiers.xsd" version="1.24">
<qualifier id="1">
<name>Alisma plantago-aquatica</name>
<attribute id="ExternalQualifierId" name="ExternalQualifierId">
<text>PAR_REF_Alisma plantago-aquatica</text>
</attribute>
<attribute id="Qualifier_TAXA" name="Qualifier_TAXA">
<description>Taxon naam</description>
<text>Alisma plantago-aquatica</text>
</attribute>
<attribute id="Type" name="Type">
<description>type</description>
<text>aquaticaType</text>
</attribute>
<attribute id="Groep" name="Groep">
<description>Familie</description>
<text>aquaticaGroup</text>
</attribute>
</qualifier>
<qualifier id="2">
<name>Butomus umbellatus</name>
<attribute id="ExternalQualifierId" name="ExternalQualifierId">
<text>PAR_REF_Butomus umbellatus</text>
</attribute>
<attribute id="Qualifier_TAXA" name="Qualifier_TAXA">
<description>Taxon naam</description>
<text>Butomus umbellatus</text>
</attribute>
<attribute id="Type" name="Type">
<description>type</description>
<text>umbellatusype</text>
</attribute>
<attribute id="Groep" name="Groep">
<description>Familie</description>
<text>umbellatusGroup</text>
</attribute>
</qualifier>
</qualifiers>
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 FewsPiService.properties.
