Page History

...

nodeId (the id of the topology node)
timeZero (the timezero for which the displaysgroups should be requested. If this parameter is ommitted the time zero will be assumed equal to the current system time

firstValueTimefirstValueTime

Example

...

requestfirstValueTime

Code Block
curl "http://localhost:8080/FewsWebServices/rest/fewspiservice/v1/displayGroups?&nodeId=groupNodeA&timeZero=2014-01-01T00:00:00Z"

...

String representation of time zone.

Example request

Code Block
curl "http://localhost:8080/FewsWebServices/rest/fewspiservice/v1/timezoneid"

...

- Filters PI-XML or PI-JSON file content.

Example request

Code Block
curl "http://localhost:8080/FewsWebServices/rest/fewspiservice/v1/filters"

...

Request parameters

filterId (string): Filter id.
documentVersion (string): File format version.
documentFormat (string): PI_XML (default), PI_JSON or GEO_JSON (since 2021.02)
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 in PI-XML, GEO_JSON or PI-JSON file content.

Example request

Code Block
curl "http://localhost:8080/FewsWebServices/rest/fewspiservice/v1/locations?showAttributes=true&documentVersion=1.24"

...

Request parameters

showAttributes (boolean): Since 2021.02. toggle to show parameter attributes. Default is false.
documentVersion (string): File format version.
documentFormat (string): PI_XML (default) or PI_JSON

Response

Parameters PI-XML or PI-JSON file content.

Example request

Code Block
curl "http://localhost:8080/FewsWebServices/rest/fewspiservice/v1/parameters"

...

Parameters PI-XML or PI-JSON file content.

Example request

Code Block
curl "http://localhost:8080/FewsWebServices/rest/fewspiservice/v1/parameters/nodes"

...

The response is always in JSON format. Note that only the most important part of the topology config is returned.

Example request

Code Block
curl "http://localhost:8080/FewsWebServices/rest/fewspiservice/v1/topology

...

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), PI_JSON, DD_JSON, NOOS_TEXT
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 timeseries values that are within this period. If the endTime doesn't match a timestamp of the time series, the closest timestamp after the endTime, will also be returned. Format: yyyy-MM-ddTHH:mm:ssZ.
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
omitEmptyTimeSeries (boolean): Toggle omitting or returning headers of empty timeSeries. Default is false. Since 2020.02.
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). These statistics are only provided if there is any data, otherwise they are left out.
- 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 timeseries values that are within this period. If the startTime doesn't match a timestamp of the time series, the closest timestamp before the startTime, will also be returned. Format: yyyy-MM-ddTHH:mm:ssZ.
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.
timeStepMillis (integer): filter time series by an equidistant timestep with a duration of the given number of milliseconds. This can be used in cases where no timestep Id has been configured in TimeSteps.xml. Cannot be used in combination with timeStepId.

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⁽¹⁾
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. If the startTime or endTime doesn't match a timestamp of the time series, the closest time step before startTime and/or after endTime is returned as well.	X		X
Apply a filter to the time series. Only time series created during the startCreationTime and endCreationTime period 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. (before 2020.01 startTime and endTime had to be specified).	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 created during the creation time period and 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.

no data vs no time series

If a timeseries query has matching timeseries sets a http 200 code will be returned and the headers of all matching timeseries sets will be returned.
If there is any data for the requested period, the headers will be followed by the actual events that contain the data. So even if no data is available for the requested period,the headers are always returned.

It is also possible that a timeseries query doesn't match any time series sets at all. This is seen as in invalid request and will result in a HTTP 400 response code.
The following are examples of use cases where this might occur:

query parameters don't occur in filter. For example: the default filter has subfilters: filterA and filterB. filterA contains timeseries sets with module instance id moduleInstanceA and filterB contains timeseries sets with module instance id moduleInstanceB. If a timeseries query is done with parameters: filterId=filterA and moduleInstanceId=moduleInstanceB, this will return in a HTTP 400 response
no timeseries for creation period. For example: if a query is using startCreationTime and endCreationTime and no time series have been produced during that period, this is seen as an invalid request and a HTTP 400 response is returned.

Example request

Code Block

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"

...

Timeseries PI-XML or PI-JSON file content..

Example request

Code Block
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"

...

Timeseries PI-XML or PI-JSON file content.

Example request

Code Block

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"

...

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 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

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.

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):

Code Block

<?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.

Code Block

language	xml
linenumbers	true

<?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.

Code Block

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

Code Block

<?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:

Code Block

<?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.

Code Block

<?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:

Code Block

language	java

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

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

Example response

Code Block

<?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 moduleruntimes (2021.02)

Get all expected runtimes for workflows per module instance id. The list can optionally be filtered by workflowId. Only workflows of scheduled tasks that contain module instance descriptors that have been configured with updateModuleRunTimesOnCompletion enabled, will be available in this end point.

The expected start time of a module is calculated based on the scheduled next due time and the expected pending duration time. The expected end time of a module is calculated based on the scheduled next due time, the expected pending duration time and the expected running time. For triggered tasks, the expected start time en end time won't be available until the task is actually started.

Request parameters

workflowId (string): optional, allow filtering for a specific worklowId.
documentFormat (string): PI_XML (default)

Response

ModuleRunTime PI XML or PI JSON content.

Example request

Code Block
curl "http://localhost:8080/FewsWebServices/rest/fewspiservice/v1/moduleruntimes?workflowId=Meuse_DWD_COSMO_LEPS"

Example response PI_XML

Code Block

<?xml version="1.0" encoding="UTF-8"?>
<ModuleRunTimes 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_moduleruntimes.xsd">
    <moduleRunTime>
        <mcId>nldefedmc00</mcId>
        <workflowId>Meuse_DWD_COSMO_LEPS</workflowId>
        <moduleInstanceId>Dummy</moduleInstanceId>
        <expectedStartTime date="2021-10-13" time="13:15:01"/>
        <expectedCompletionTime date="2021-10-13" time="13:16:54"/>
        <expectedPendingDuration>1465</expectedPendingDuration>
        <expectedRunningDuration>112634</expectedRunningDuration>
    </moduleRunTime>
</ModuleRunTimes>

Example response PI_JSON

Code Block

{
  "moduleRunTimes" : [ {
    "workflowId" : "Meuse_DWD_COSMO_LEPS",
    "moduleInstanceId" : "Dummy",
    "mcId" : "nldefedmc00",
    "expectedStartTime" : 1414882800000,
    "expectedCompletionTime" : 1414886400000,
    "expectedPendingDuration" : 1465,
    "expectedRunningDuration" : 112634
  } ]
}

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 successful
null= No status available (produces when method call times-out)

Example request

Code Block
curl "localhost:8080/FewsWebServices/rest/fewspiservice/v1/taskrunstatus?taskId=1_0"

Example response

Code Block
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

Code Block

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

Code Block
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

Code Block
curl "http://localhost:8080/FewsWebServices/rest/fewspiservice/v1/timeseriesmodifiers"

Example response

Code Block

<?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

Code Block
curl "http://localhost:8080/FewsWebServices/rest/fewspiservice/v1/modifiers?modifierTypeId=MISSING_VALUE_MODIFIER"

Example response

Code Block

<?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

Code Block

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

Code Block

<?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

Code Block
curl "http://localhost:8080/FewsWebServices/rest/fewspiservice/v1/workflows"

Example response

Code Block

<?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>

...

Samples PI XML file content

Example request

Code Block
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"

...

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

Code Block

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"

...

Response

Qualifiers in PI-XML.

Example request

Code Block
curl "http://localhost:8080/FewsWebServices/rest/fewspiservice/v1/locations?showAttributes=true&documentVersion=1.24"

...

Content of the csv file of the module run table. Dates are in GMT-0 in the format: yyyyMMddHHmmss
The csv file name is returned in the Content-Disposition header: attachment;filename=filename.csv

Example request

Code Block
curl "http://localhost:8080/FewsWebServices/rest/fewspiservice/v1/moduleruntables/current?moduleInstanceId=myModuleInstance"

...

Page tree

Page History

Versions Compared

Old Version 222

New Version 223

Key

Example

requestfirstValueTime

Example request

Example request

Request parameters

Response

Example request

Request parameters

Response

Example request

Example request

Example request

Request parameters

Response

Filter combinations

no data vs no time series

Example request

Example request

Example request

POST timeseries (2017.02)

Request parameters

Body parameters

Response

Example request

Example response

Example response with non-matching time series.

Example forecast time series.

Example code

GET taskruns

Request parameters

Response

Example request

Example response

GET moduleruntimes (2021.02)

Request parameters

Response

Example request

Example response PI_XML

Example response PI_JSON

GET taskrunstatus (2017.02)

Request parameters

Response

Example request

Example response

POST runtask (2017.02)

Request parameters

Body parameters

Response

Example request

Example response

GET timeseriesmodifiers (2017.02)

Request parameters

Response

Example request

Example response

GET modifiers

Request parameters

Response

Example request

Example response

POST modifiers (2017.02)

Request parameters

Body parameters

Response

Example request

Example response

GET workflows (2017.02)

Request parameters

Response

Example request

Example response

Example request

Example request

Response