Versions Compared

Old Version 131

changes.mady.by.user Rudie Ekkelenkamp

Saved on

compared with

New Version 132

changes.mady.by.user Rudie Ekkelenkamp

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Code Block
<?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 list of parameters that are available in the archive. Optionally the parameters can be filtered by one or more location ids or archive attributesa 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.

Warning

If no line, area or bar elements is used in the displayGroups.xml configuraiton, the TimeSeriesSets will not be applied.


Request parameters

  • locationIdsconvertDatum (stringboolean): 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.
  • 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

Example query

Code Block
languagexml
http://localhost:8080/FewsWebServices/rest/fewspiservice/archive/parameters?attribute(storageId)=storageA

Example response:

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

...

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

Code Block
curl "

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

Code Block
languagexml
http://localhost:8080/FewsWebServices/rest/fewspiservice/archivev1/timeseries/locations?attribute(storageId)=storageA

Example response:

Code Block
<?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/products (2019.02)

Returns a zip-file with the requested products from the archive.  

Request parameters

...

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

...

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

GET timeseries/displaygroups (2019.02)

...

parameters?attribute(storageId)=storageA

Example response:

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

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.

Warning

If no line, area or bar elements is used in the displayGroups.xml configuraiton, the TimeSeriesSets will not be applied.

...

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

Example query

Code Block
languagexml
http://localhost:8080/FewsWebServices/rest/fewspiservice/archive/locations?attribute(storageId)=storageA

Example response:

Code Block
<?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/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 productsuseMilliseconds (boolean) Optional argument. Default is false. If it is set to true, the response will contain milliseconds. See example bellow.
  • 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

  • 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


Code Block
languagexml
Code Block
curl "http://localhost:8080/FewsWebServices/rest/fewspiservice/v1/timeseriesarchive/displaygroupsproducts?plotIdareaId=TidalForecastsmyAreaId&locationIdssourceId=UKCFF_ABDmySourceId&startTime=20192011-0610-10T0010T12:00:00Z&endTime=20192021-0610-25T0010T12:00:00Z"

Example PI-XML and JSON response

...

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

Request parameters

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

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

Body parameters

  • piTimeSeriesXmlContent (xml string, required): PiTimeseries xml file  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
    languagexml
    linenumberstrue
    <?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.

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>

 

...