Page History

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 timeseriestime series. Note: creation time of timeseries time series is actually the creation time of the task that produced/imported these timeseriestime series.
• endForecastTime (dateTime: yyyy-MM-ddTHH:mm:ssZ): End time of search period that looks for timeseries produced 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 time series values that lie within this period.
• ensembleId (string): Ensemble identifier of for timeseriestime 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 timeseriestime series. This parameter can be duplicated to use multiple locationIds.
• moduleInstanceIds (string): Subset of moduleInstances for which to retrieve timeseriestime 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 timeSeries time series (Since 2017.02)
• onlyManualEdits (boolean): Toggle to return only manual edits.
• parameterIds (string): Subset of parameters for which to retrieve timeseriestime series. This parameter has to be duplicated to specify multiple parameters.
• qualifierIds (string): Subset of qualifiers for which to retrieve timesierestime 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 timeseriestime series. Typically used in combination with onlyHeaders. Returns additional information about data availability of timeseries time series (Since 2015.01). 
  
  • firstValueTime: First time with a value in the timeSeriestime series
  • lastValueTime: Last time with a value in the timeSeriestime series
  • maxValue: Maximum value in the timeSeriestime series
  • minValue: Minimum value in the timeSeriestime series
  • valueCount: Number of values in the timeSeriestime 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 timeSeriestime 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 timeSeries 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 timeseriestime series. Note: creation time of timeseries time series is actually the creation time of the task that produced/imported these timeseriestime series.
• startForecastTime (dateTime: yyyy-MM-ddTHH:mm:ssZ): Start time of search period that looks for timeseries 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 time series values that lie within this period.
• taskRunIds (string): Subset of task run ids for which to retrieve timeseriestime series.   This 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 timeseries 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

• Timeseries 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.

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

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.

In case a time series already exists in the database, the time series will be overwritten by the ones that are posted.

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.

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 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());

}