Timeseries Instance

Endpoint for interacting with timeseries metadata and events.

In absence of startTime and endTime query parameters, no events will be returned to avoid unintentionally large responses. Events are raw (i.e. not aggregated) by default, but may be aggregated by specifying a min_points or window parameter. Aggregated events have several characteristics, which may be exposed via fields parameters.

Retrieving raw events for large periods is best done asynchronously. See the async parameter below.

Query parameters

async: Requests can be handled asynchronously by specifying async=true. This is particularly useful when retrieving events for many timeseries and/or large periods, which may result in time-outs otherwise.

fields: Controls how (aggregated) events are serialized. Multiple fields parameters may be present. Possible values are: avg, count, first, first_timestamp, last, last_timestamp, max, max_timestamp, min, min_timestamp, nans, size, and sum. When working with raw events, fields=value will return familiar timestamp-value pairs.

startTime: Temporal filter on startTime. Supports various lookup types (startTime__exact by default). Filter values should be specified in ISO 8601 YYYY-MM-DDThh:mm:ssZ format.

format: Controls in what format the reponse is. Possible values: json and api (the default). Another way of controlling this, is by sending an Accept HTTP header field in the request, e.g. Accept: application/json.

endTime: Temporal filter on endTime. Supports various lookup types (endTime__exact by default). Filter values should be specified in ISO 8601 YYYY-MM-DDThh:mm:ssZ format.

location: Related filter on location. See the locations endpoint.

median: Include this argument to get the 50th percentile for every timeseries.

min_points: Controls the number of events to be returned. The system will automatically choose an aggregation level that yields a minimum number of (aggregated) events, but no less than min_points, if possible.

name: Text filter on name. Supports various lookup types (name__exact by default).

no_events: Include this arguments to not collect events (events are returned as null).

ordering: Offers basic ordering functionality on the last_modified and name attributes of timeseries. Orderings may be reversed by prefixing the attribute with '-'.

organisation_code (or just code for short): Text filter on code. Supports various lookup types (organisation_code__exact by default).

page: To prevent system overloads, list-view results are paginated. This parameter specifies which page to return.

pageSize: The maximum number of results to return in list-view. The default is 10.

percentiles: Either a comma-seperated list of requested percentiles (e.g. 1.20,5 ) or just this argument without value. The latter case includes a list of all cardinal percentiles from 0 to 100.

search: Offers basic search functionality on the name attribute of timeseries and associated locations. More advanced search functionality is available via the search endpoint.

startTime/endTime: Both query parameters are required to obtain events. They define an interval [startTime, endTime) and should be either in ISO 8601 YYYY-MM-DDThh:mm:ssZ format or in milliseconds since the epoch.

supplier: Related filter on supplier. See the users endpoint.

supplier_code: Text filter on supplier_code. Supports various lookup types (supplier_code__exact by default).

id: Text filter on uuid. Supports a comma-separated list of (fragments of) UUIDs. Supports id__icontains and id__iexact as default.

value_type: Number filter on value_type. Values in use are: 0 (integer), 1 (float), 4 (text), 5 (image), 8 (movie), 10 (file), 12 (float array). Supports various lookup types (value_type__exact by default).

window: Temporal aggregation window. One of raw, second, minute, 5min, hour, day, week, month, or year. Takes precedence over min_points. When used with percentiles, the percentiles are aggregated over month or year digests only.

timezone: If window is day or longer, the aggregation depends on the timezone. By default, aggregations are done in UTC (fastest). Supply another timezone (e.g. Europe/Amsterdam) to perform aggregation in local days (months, years) NB: This only effects the aggregation buckets, not the timestamps themselves, which are always UTC.

intervalLength: Timestep between measurements in seconds for equidistant Timeseries. A Timeseries with an interval of 0 or null is considered nonequidistant.

Examples

?location__locationName=Valkenburg

?location__object_type__model=pumpstation&location__object_id=1

?object=pumpstation$1 (a shorthand for above)

?median&window=year&no_events

?name=WNS1400.1d

?ordering=-last_modified

?organisation_code__startswith=WNS1400

?page=25&pageSize=4

?percentiles&no_events

?percentiles=5,50,95&no_events

?search=Valkenburg

?startTime__gte=2017-01-01T00:00:00Z

?endTime__lt=2018-01-01T00:00:00Z

?startTime=2016-08-27T12:15:00Z&endTime=2016-08-28T12:15:00Z

?startTime=1472300100000&endTime=1472386500000&fields=value

?supplier__email__endswith=satelligence.com

?supplier_code__isnull=False

?id=88f7-4c9f-8f28,15ea-4b7f-b2ed

?id__icontains=88f7-4

?value_type__in=0,1

?intervalLength=1000

As a more elaborate example, below is shown how to retrieve raw events (without metadata) for a particular timeseries in an asynchronous way. This example combines several of the above query string parameters.

https://demo.lizard.net/api/v3/timeseries/<UUID>/data/ ↵
?startTime=1262304000000&endTime=1478794500000&fields=value&format=json&async=true