About

This API development intends to make near realtime sensor data (provided by OGCSensor Observation Services) better accessible for leightweight clients like mobile devices. However, in addition to the actual Web access layer the Timeseries API offers a Service Provider Interface (SPI) which can be implemented to adapt arbitrary data sources.

General

Content-Types

The API provides different content types which can be used to retrieve different types of representation of a requested resource. The actual content types differ for each resource so the ones supported are documented in the appropriate section.

The only content type supported by each resource is application/json. It is set as the default content type but can be set either via HTTP header or by .json extension.

Common Query Parameters

Each parameter is optional and can only contain one value. Multiple parameters are combined to an AND query. A resource may specify further query parameters to control/filter output. Special query parameters are described in each section.

Parameter

Example

Description

expanded

expanded=true

If true a list of partially expanded resource items is returned. The expansion provides more detailed information up to a certain point. However, it does not necessarily provide all item information as one may get when request the resource item itself.

The expanded works almost only for resource collection. However, exceptions may exist (e.g. for timeseries raw data). Exceptions are explicitly documented.

Lists extra metadata which may vary from instance to instance. The available metadata fields
are listed in the extras metadata section of a timeseries. You can query just
the ones you are interested in by appending the fields query parameter and passing
a comma-separated value list to it. For example
http://localhost:8080/sensorwebclient-webapp/api/v1/timeseries/{id}/extras?fields=license

GET

/api/v1/timeseries/{id}/{interval}

image/png

Returns an image of timeseries with id {id} for the given {interval}. Allowed interval values are

lastDay

lastWeek

lastMonth

Timeseries can be pre-rendered by a regular task. If pre-rendering is enabled for a given timeseries depends on the API provider as it is a configuration issue.

If a timeseries has no pre-rendered chart a 404 (Resource not found) error is returned. In particular cases this is also true when the chart is currently being re-rendered.

Request Data

Timeseries data is actually not modelled as a resource itself. Data requests can be triggered by appending the getData verb.

Method

Path

Content-Type

Description

GET

/api/v1/timeseries/{id}/getData

application/json

Lists the raw data of timeseries with id {id}.

GET

/api/v1/timeseries/{id}/getData

image/png

Draws a graph of the data of timeseries with id {id}.

POST

/api/v1/timeseries/getData

application/json

Request the metadata for multiple timeseries. The requested timeseries ids have to be contained in the POST request.

Exports the given stack of timeseries to the given output format. The requested timeseries ids have to be contained in the POST request.

Each timeseries can be styled (chart type, color, widths, etc) by passing style options. Have a look at the POST request example or check out the request schema how a POST request shall look like to render multiple timeseries.

Query Parameters

Timeseries data can be queried with the following filter parameters.

Parameter

Example

Description

expanded

expanded=true

The expanded parameter works for collection data and also when requesting raw timeseries data.

Timeseries may provide additional data which changes over time (and therefore is not core metadata anymore). Best example are reference values which can be used to provide better interpretation to actual data values.

The force_latest_values parameter can be used to force last value requests on a collection of timeseries.

Please note that this enforcement (in combination with expanded=true) may result is long response times as the last value has to be requested for each timeseries of the requested collection. Use this enforcement only on filtered queries.

format

format=highcharts

Controls the output format of raw timeseries data. This avoids converting between different data formats on client side which uses a 3rd party chart rendering API. Currently, supported formats:

Timeseries data can get huge quickly depending on how often new values are measured and how long data is stored in the corresponding data backend! Naive clients can bother data providers when trying to request huge datasets by accident. Therefore data requests may be limited to a maximum timespan (per configuration).

However, most probably consuming huge datasets may also not be of client's interest. Have a look at the paging documentation how to get data in smaller chunks.

If you are interested in the PNG output you can either parse it from your favorite programming language. For a quick review you can use Curl from command line (adapt parameters as needed, e.g. if you want a PDF report instead):

Example

Data Formats

Raw data can be requested in a specific format. This can be useful if you work with a specific chart API and want to avoid to convert data outout from one format to another. Possible formats are:

tvp (the default)

highchart

To retrieve extra reference values (if available for that timeseries) valid for the requested timespan just add expand=true.

Serving arbitrary formats is limited. Most probably you have to combine timeseries metadata and the actual data differently within the used API. Please refer to the actual data output so that it can be used as intended by the 3rd party API.

Please note that when adding expanded=true, reference values will be added as a timeseries on their own. You can track reference values with the corresponding identifiers available from the timeseries metadata.

Generalization

Depending on sampling resolution and timespan timeseries data can be huge. Generalizing data
can make sense in more than just a low bandwidth use case (e.g. smoothing the curve).

The API supports two generalization algorithms which can be enabled by generalize=true.
Default generalization behaviour is set to false (may be configurable in future).
More algorithms can be added easily.

An expanded view gives you a bit more metadata about a service instance. It counts the amount of available resources and gives you information about the serivce's capabilities, e.g. if first and latest value requests are supported.

Unstable/Legacy

This section describe non public functionlity which may be either unstable or legacy to be kept for backward compatibility.

Offerings

URLs

API calls are triggered by using the following URLs.

Method

Path

Content-Type

Description

GET

/api/v1/offerings

application/json

Lists all offerings available.

GET

/api/v1/offerings/{id}

application/json

Lists the offering with id {id}.

Query Parameters

Except the Resources collection all other collections can be queried/filtered by using the following query parameters. Each parameter is optional and can only contain one value. Multiple parameters are combined to an AND query. A resource may specify further query parameters to control/filter output. Special query parameters are described in each section.

Query Parameters

Except the Resources collection all other collections can be queried/filtered by using the following query parameters. Each parameter is optional and can only contain one value. Multiple parameters are combined to an AND query. A resource may specify further query parameters to control/filter output. Special query parameters are described in each section.

Query Parameters

Except the Resources
collection all other collections can be queried/filtered by
using the following query parameters. Each parameter is optional
and can only contain one value. Multiple parameters are combined
to an
AND
query. A resource may specify further query parameters to
control/filter output. Special query parameters are described in
each section.