Timeseries URL

Get all records in a time range

To retrieve all the time series records in a time range, append /timeseries to the URL and specify the time range with from and to parameters:

{ApiServerUrl}/namespace/Entity/timeseries?from={date}&to={date}...

For example:

{ApiServerUrl}/${namespace}/${entity}/timeseries?limit=10000&from=2017-01-01Z&to=2017-01-07Z...

Note: This URL retrieves a very large number of updates equal to the number of ${entity} instances multiplied by the update frequency and the time range. Always specify a limit parameter to restrict the results returned from the /timeseries service. If no limit is specified, a default of 10,000 is applied by the REST API server.

Important: When requesting timeseries data with from and to parameters, you must not specify the rangeField parameter, which is always the timeseries field of the entity.

from and to are optional. If they are omitted, they have the following meaning:

  • If from is omitted, this is equivalent to setting from to a point infinitely far in the past.
  • If to is omitted, this is equivalent to setting to to a point infinitely far in the future.

Get all records in a time range for specific IDs

To retrieve all records in a time range for a list of technical identifiers, add an id parameter to the above request:

{ApiServerUrl}/namespace/Entity/timeseries?limit=10000&from=DATE&to=DATE&id={1},{2},...

Other lookup fields can be used as well in a timeseries request, but range field requests are not possible. The only range that can be specified is the timeseries range.

Limit the number of results

Add the limit parameter to restrict the number of results to a specified number.

Note: The timeseries URL limits the maximum number of results to 10,000. It is an error to specify a limit higher than 10,000.

Important: Important: If the history request encompasses more than 10,000 results, you must repeat the request to download all the results in batches of 10,000:

  • Set the limit parameter to 10,000 and then add the after parameter on subsequent requests, where after equals the id,dateTime of the last record in the previous response. The dateTime part is the value of the timeseries field of the entity..
  • Repeat this process until the API returns an empty array of results, indicating no further content beyond the last combination of ID and dateTime provided.

For example, request 1 below requests all data from DATE1 to DATE2 with a limit of no more than 10,000 results in the response. Request 2 sets after to the id,asOf of the last record in the previous response. This process is repeated until a request returns an empty array (no further data matches the request).

  1. {ApiServerUrl}/${namespace}/${entity}/timeseries?from=DATE1&to=DATE2&limit=10000...
  2. {ApiServerUrl}/${namespace}/${entity}/timeseries?from=DATE1&to=DATE2&limit=10000&after=lastId,lastAsOf...
  3. {ApiServerUrl}/${namespace}/${entity}/timeseries?from=DATE1&to=DATE2&limit=10000&after=lastId2,lastAsOf2...
  4. ...

Latest and timeseries lookups

It is possible to use all lookup fields in /timeseries requests, but it is important to understand that there are two kinds of lookup field for timeseries requests:

  • Latest lookups: these lookups are evaluated using latest data only to create a list of ids that are then evaluated in the /timeseries request. If the lookup field has different values earlier in the timeseries, these differences are ignored.
  • Timeseries lookups: these lookups are evaluated on the timeseries service directly. If a timeseries lookup only matches the search criteria for part of the time range, then only that part of the time range is returned.

Latest lookups serve as a means to provide additional filtering functionality on the /timeseries collections, but at the cost that only latest data is used in the filtering.

You can view which fields are latest lookups on the REST API console in a Web browser:

{ApiServerUrl}/${namespace}/${entity}/timeseries?limit=1&format=HTML

Group by ID

The /timeseries service can group results by id for a given time range. Ordinarily, the /timeseries service gives multiple results for any id, but by setting the parameter groupById, only a single result will be returned for any id. groupById can have the following values:

  • first: returns the earliest update for each id in the supplied from and to time range.
  • last: returns the latest update for each id in the supplied from and to time range.

For example, to get the "opening" values for a set of records, set groupById=first. Likewise, to get the "closing" values for a set of records, set groupById=last.

The groupById feature requires a set of ids as input. This can be provided with the id lookup field or by filtering on another lookup field. You can use any latest lookup field. Timeseries lookups are not supported for groupById requests.

Example: {ApiServerUrl}/${namespace}/${entity}/timeseries?limit=3&id=ID1,ID2,ID3&from=2021-01-01&to=2021-02-01&format=HTML&groupById=last

Back to help overview