...
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 20212020.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).
- 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(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. 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.
...
- 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
- 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.
- 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
- omitEmptyTimeSeries (boolean): Toggle omitting or returning headers of empty timeSeries. Default is false. Since 20212020.02.
- 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 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.
- useDisplayUnits (boolean): Export values using display units.
...
- bbox (string, required): 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), PI_JSON, DD_JSON, NOOS_TEXT
- 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 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.
- 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
- omitEmptyTimeSeries (boolean): Toggle omitting or returning headers of empty timeSeries. Default is false. Since 20212020.02.
- 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 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.
- 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 position on the map in EPSG:3857 format.
- y (double, required): y position on the map in EPSG:3857 format.
...