Time Series Database (TSDB) Smart Module endpoints for managing simple time series or time series collections, and for retrieving data stored in TSDB for this home.

Endpoints

The Simple Time Series object

  • idstring

    Identifier of time series. Must not have more than 128 characters.

  • homeIdinteger

    Home that this time series belongs to.

  • moduleIdstring

    ID of Smart Module that created this time series.

  • timeZonestring

    If present, time series is associated with a time zone that is not UTC. This should be a time zone name defined in the IANA TZ Database.

The Time Series Collection object

  • idstring

    Identifier of collection. Must not have more than 128 characters.

  • homeIdinteger

    Home that this collection belongs to.

  • moduleIdstring

    ID of Smart Module that created this collection.

  • timeZonestring

    If present, collection is associated with a time zone that is not UTC. This should be a time zone name defined in the IANA TZ Database.

  • valueNamesarray

    List of unique Identifiers of numerical fields in collection.

  • tagNamesarray

    List of unique Identifiers of string tags in collection.

The Time Series Export Request object

  • seriesIdsarray

    Array of series IDs whose data are to be exported.

  • collectionIdsarray

    Array of collection IDs whose data are to be epxorted.

  • beginstring| format is date-time

    The beginning timestamp of the export time range (in RFC3339).

  • endstring| format is data-time

    The ending timestamp of the export time range (in RFC3339).

  • includeHeaderboolean

    If true, each exported CSV file will start with a header. Used only when exporting collections.

Export time series data

Endpoint
post /homes/{homeId}/smartModules/{moduleId}/export
Description

Export the data in one or more time series or time series collections. The request body must be a valid Time Series Export Request object. Use the seriesIds field in the request object to export time series, or the collectionIds field to export collections.

Path Parameters
  • homeId

    integer

    required

    The unique id for a home.

  • moduleId

    string

    required

    The unique id for a smart module.

Request Headers What's this?
  • Authorization

    required

    Must contain a user or project API key.

Response
  • 200The URLs for downloading the exported data are returned.
  • 401Authorization is required to access this resource.
  • 403Request failed because of invalid request parameters.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Request Body Sample

{
  "seriesIds": [
    "rm1_humidity",
    "rm1_temperature"
  ],
  "begin": "2019-05-10T10:00:00Z",
  "end": "2019-05-11T13:00:00Z"
}

Get all time series

Endpoint
get /homes/{homeId}/smartModules/{moduleId}/timeSeries
Description

Get the list of all time series being stored for this home.

Path Parameters
  • homeId

    integer

    required

    The unique id for a home.

  • moduleId

    string

    required

    The unique id for a smart module.

Request Headers What's this?
  • Authorization

    required

    Must contain a user or project API key.

Response
  • 200An array of time series objects are returned.
  • 401Authorization is required to access this resource.
  • 403Request failed because of denied permission.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Create a time series

Endpoint
post /homes/{homeId}/smartModules/{moduleId}/timeSeries
Description

Create a new time series for this home. Normally a time series is automatically created when data points are first injected. However, such time series are automatically defaulted to the UTC time zone. Time series that are meant to be in a specific time zone should be explicitly created with this endpoint ahead of time, before any data points are injected. The request body must contain the id and timeZone fields.

Path Parameters
  • homeId

    integer

    required

    The unique id for a home.

  • moduleId

    string

    required

    The unique id for a smart module.

Request Headers What's this?
  • Authorization

    required

    Must contain a user or project API key.

Response
  • 201Time series successfully created.
  • 401Authorization is required to access this resource.
  • 403Request failed because of invalid data or denied permission.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Request Body Sample

{
  "id": "room1_humidity",
  "timeZone": "Asia/Tokyo"
}

Get time series

Endpoint
get /homes/{homeId}/smartModules/{moduleId}/timeSeries/{seriesId}
Description

Get the information of a specific time series.

Path Parameters
  • homeId

    integer

    required

    The unique id for a home.

  • moduleId

    string

    required

    The unique id for a smart module.

  • seriesId

    string

    required

    Series ID. It must be unique per home.

Request Headers What's this?
  • Authorization

    required

    Must contain a user or project API key.

Response
  • 200The requested time series object is returned.
  • 401Authorization is required to access this resource.
  • 403Request failed because of denied permission.
  • 404The requested timeSery does not exist or is not accessible.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Response Body Sample

{
  "id": "room1-temperature",
  "homeId": 2233,
  "moduleId": "sensor_data",
  "timeZone": "Europe/Berlin"
}

Delete time series

Endpoint
delete /homes/{homeId}/smartModules/{moduleId}/timeSeries/{seriesId}
Description

Delete a specific time series and all its data.

Path Parameters
  • homeId

    integer

    required

    The unique id for a home.

  • moduleId

    string

    required

    The unique id for a smart module.

  • seriesId

    string

    required

    Series ID. It must be unique per home.

Request Headers What's this?
  • Authorization

    required

    Must contain a user or project API key.

Response
  • 204Time series successfully deleted.
  • 401Authorization is required to access this resource.
  • 403Request failed because of invalid data or denied permission.
  • 404The required timeSery does not exist or is not accessible.
  • 409The timeSery cannot be deleted because it is being used by another part of the system.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Get time series data

Endpoint
get /homes/{homeId}/smartModules/{moduleId}/timeSeries/{seriesId}/data
Description

Get the time series data specified by series ID. Use the begin and end parameters to fetch values by time range, with the proper time resolution automatically applied. Use the ts and limit parameters to fetch a specific number of data points before or after a point in time.

Path Parameters
  • homeId

    integer

    required

    The unique id for a home.

  • moduleId

    string

    required

    The unique id for a smart module.

  • seriesId

    string

    required

    Series ID. It must be unique per home.

Query Parameters
  • begin

    string

    required

    The beginning of the time series data. The format follows RFC3339.

  • end

    string

    required

    The end of the time series data. The format follows RFC3339.

  • aggregation

    string

    required

    Aggregation function. The string must be either 'avg', 'min', 'max', 'sum' or 'count'. 'avg' is chosen if not provided.

  • ts

    string

    required

    The point in time (in RFC3339) to fetch data points from.

  • limit

    integer

    required

    If positive, this is the maximum number of data points at and after ts to be returned. If negative, this is the maximum number of data points before ts to be returned.

Request Headers What's this?
  • Authorization

    required

    Must contain a user or project API key.

Response
  • 200The requested time series data points are returned.
  • 401Authorization is required to access this resource.
  • 403Request failed because of denied permission.
  • 404The requested datum does not exist or is not accessible.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Response Body Sample

{
  "seriesId": "room1-temperature",
  "begin": "2019-04-11T07:51:46.712Z",
  "end": "2020-01-29T01:26:08.101Z",
  "aggregation": "avg",
  "resolution": "1day",
  "data": [
    ["2019-04-11T00:00:00Z", 22.97349639133924],
    ["2019-04-12T00:00:00Z", 22.916217542079057],
    ["2019-04-13T00:00:00Z", 21.939217256214157],
    ["2019-04-14T00:00:00Z", 21.668999574649146],
    ["2019-04-15T00:00:00Z", 23.01144695453247],
    ["2019-04-16T00:00:00Z", 23.877712361878466],
    ["2019-04-17T00:00:00Z", 24.251540345449843],
    ["2019-04-18T00:00:00Z", 23.900341664030382],
    ["2019-04-19T00:00:00Z", 23.579976112920807]
  ]
}

Delete time series data

Endpoint
delete /homes/{homeId}/smartModules/{moduleId}/timeSeries/{seriesId}/data
Description

Delete data points of a time series that fall within a given time range. If only the begin parameter is specified, all data timestamped after begin will be deleted. If only the end parameter is specified, all data timestamped before end will be deleted.

Path Parameters
  • homeId

    integer

    required

    The unique id for a home.

  • moduleId

    string

    required

    The unique id for a smart module.

  • seriesId

    string

    required

    Series ID. It must be unique per home.

Query Parameters
  • begin

    string

    required

    The beginning of the time range. The format follows RFC3339.

  • end

    string

    required

    The end of the time range. The format follows RFC3339.

Request Headers What's this?
  • Authorization

    required

    Must contain a user or project API key.

Response
  • 204The data points have been successfully deleted.
  • 401Authorization is required to access this resource.
  • 403Request failed because of invalid data or denied permission.
  • 404The required datum does not exist or is not accessible.
  • 409The datum cannot be deleted because it is being used by another part of the system.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Get time series time range

Endpoint
get /homes/{homeId}/smartModules/{moduleId}/timeSeries/{seriesId}/timeRange
Description

Get the timestamp of the first and last data points in the specified time series.

Path Parameters
  • homeId

    integer

    required

    The unique id for a home.

  • moduleId

    string

    required

    The unique id for a smart module.

  • seriesId

    string

    required

    Series ID. It must be unique per home.

Request Headers What's this?
  • Authorization

    required

    Must contain a user or project API key.

Response
  • 200The requested time range is returned.
  • 401Authorization is required to access this resource.
  • 403Request failed because of denied permission.
  • 404The requested timeRange does not exist or is not accessible.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Response Body Sample

{
  "seriesId": "room1-temperature",
  "begin": "2018-12-11T17:00:22Z",
  "end": "2020-01-29T01:26:08.101Z"
}

Get all time series collections

Endpoint
get /homes/{homeId}/smartModules/{moduleId}/collections
Description

Get the list of all time series collections being stored for this home.

Path Parameters
  • homeId

    integer

    required

    The unique id for a home.

  • moduleId

    string

    required

    The unique id for a smart module.

Request Headers What's this?
  • Authorization

    required

    Must contain a user or project API key.

Response
  • 200An array of time series collections are returned.
  • 401Authorization is required to access this resource.
  • 403Request failed because of denied permission.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Create a time series collection

Endpoint
post /homes/{homeId}/smartModules/{moduleId}/collections
Description

Create a new time series collection for this home. Normally a collection is automatically created when data points are first injected. However, such collections are automatically defaulted to the UTC time zone. Collections that are meant to be in a specific time zone should be explicitly created with this endpoint ahead of time, before any data points are injected. The request body must contain the id and timeZone fields.

Path Parameters
  • homeId

    integer

    required

    The unique id for a home.

  • moduleId

    string

    required

    The unique id for a smart module.

Request Headers What's this?
  • Authorization

    required

    Must contain a user or project API key.

Response
  • 201Collection successfully created.
  • 401Authorization is required to access this resource.
  • 403Request failed because of invalid data or denied permission.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Request Body Sample

{
  "id": "sensor1_measurements",
  "timeZone": "America/New_York"
}

Get time series collection

Endpoint
get /homes/{homeId}/smartModules/{moduleId}/collections/{collectionId}
Description

Get the information of a specific time series collection.

Path Parameters
  • homeId

    integer

    required

    The unique id for a home.

  • moduleId

    string

    required

    The unique id for a smart module.

  • collectionId

    string

    required

    Collection ID. It must be unique per home.

Request Headers What's this?
  • Authorization

    required

    Must contain a user or project API key.

Response
  • 200Info of the requested time series collection is returned.
  • 401Authorization is required to access this resource.
  • 403Request failed because of denied permission.
  • 404The requested collection does not exist or is not accessible.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Response Body Sample

{
  "id": "room1-metrics",
  "homeId": 2233,
  "moduleId": "sensor_data",
  "timeZone": "Europe/Berlin",
  "valueNames": ["temperature", "humidity", "pressure"],
  "tagNames": ["vendor_id", "occupant"]  
}

Delete time series collection

Endpoint
delete /homes/{homeId}/smartModules/{moduleId}/collections/{collectionId}
Description

Delete a specific collection and all its data.

Path Parameters
  • homeId

    integer

    required

    The unique id for a home.

  • moduleId

    string

    required

    The unique id for a smart module.

  • collectionId

    string

    required

    Collection ID. It must be unique per home.

Request Headers What's this?
  • Authorization

    required

    Must contain a user or project API key.

Response
  • 204Collection successfully deleted.
  • 401Authorization is required to access this resource.
  • 403Request failed because of invalid data or denied permission.
  • 404The required collection does not exist or is not accessible.
  • 409The collection cannot be deleted because it is being used by another part of the system.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Get collection data

Endpoint
get /homes/{homeId}/smartModules/{moduleId}/collections/{collectionId}/data
Description

Get the collection data specified by collection ID. Use the begin and end parameters to fetch entries by time range, with the proper time resolution automatically applied. Use the ts and limit parameters to fetch a specific number of entries before or after a point in time. Use the selectValues parameter to specify which value fields of the collection should be returned. When raw data entries are being fetched, it is possible to use the selectTags parameter to retrieve the tag fields from the entries as well.

Path Parameters
  • homeId

    integer

    required

    The unique id for a home.

  • moduleId

    string

    required

    The unique id for a smart module.

  • collectionId

    string

    required

    Collection ID. It must be unique per home.

Query Parameters
  • begin

    string

    required

    The beginning time of the data entries. The format follows RFC3339.

  • end

    string

    required

    The end time of the data entries. The format follows RFC3339.

  • aggregation

    string

    required

    Aggregation function. The string must be either 'avg', 'min', 'max', 'sum' or 'count'. 'avg' is chosen if not provided.

  • ts

    string

    required

    The point in time (in RFC3339) to fetch data entries from.

  • limit

    integer

    required

    If positive, this is the maximum number of data entries at and after ts to be returned. If negative, this is the maximum number of data points before ts to be returned.

  • selectValues

    string

    required

    A comma-delimited list of value names. Since each data entry in the collection contains multiple value fields, the fields to be returned must be specified

  • selectTags

    string

    required

    A comma-delimited list of tag names. This is used only when fetching entries with the ts and limit parameters. If data entries contain tags, use this parameter to return the desired tag fields.

Request Headers What's this?
  • Authorization

    required

    Must contain a user or project API key.

Response
  • 200The requested collection data entries are returned.
  • 401Authorization is required to access this resource.
  • 403Request failed because of denied permission.
  • 404The requested datum does not exist or is not accessible.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Response Body Sample

{
  "collectionId": "room1-metrics",
  "begin": "2019-04-11T07:51:46.712Z",
  "end": "2020-01-29T01:26:08.101Z",
  "aggregation": "avg",
  "resolution": "1day",
  "data": [
    ["2019-04-11T00:00:00Z", 22.97349639133924, 0.66, 772],
    ["2019-04-12T00:00:00Z", 22.916217542079057, 0.77, 899],
    ["2019-04-13T00:00:00Z", 21.939217256214157, 0.80, 502],
    ["2019-04-14T00:00:00Z", 21.668999574649146, 0.50, 888],
    ["2019-04-15T00:00:00Z", 23.01144695453247, 0.55, 890],
    ["2019-04-16T00:00:00Z", 23.877712361878466, 0.63, 792],
    ["2019-04-17T00:00:00Z", 24.251540345449843, 0.45, 662],
    ["2019-04-18T00:00:00Z", 23.900341664030382, 0.80, 705],
    ["2019-04-19T00:00:00Z", 23.579976112920807, 0.78, 780]
  ]
}

Delete collection data

Endpoint
delete /homes/{homeId}/smartModules/{moduleId}/collections/{collectionId}/data
Description

Delete data entries of a time series collection that fall within a given time range. If only the begin parameter is specified, all entries timestamped after begin will be deleted. If only the end parameter is specified, all entries timestamped before end will be deleted.

Path Parameters
  • homeId

    integer

    required

    The unique id for a home.

  • moduleId

    string

    required

    The unique id for a smart module.

  • collectionId

    string

    required

    Collection ID. It must be unique per home.

Query Parameters
  • begin

    string

    required

    The beginning of the time range. The format follows RFC3339.

  • end

    string

    required

    The end of the time range. The format follows RFC3339.

Request Headers What's this?
  • Authorization

    required

    Must contain a user or project API key.

Response
  • 204The data entries have been successfully deleted.
  • 401Authorization is required to access this resource.
  • 403Request failed because of invalid data or denied permission.
  • 404The required datum does not exist or is not accessible.
  • 409The datum cannot be deleted because it is being used by another part of the system.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Get time range of collection data

Endpoint
get /homes/{homeId}/smartModules/{moduleId}/collections/{collectionId}/timeRange
Description

Get the timestamp of the first and last data entries in the specified time series collection.

Path Parameters
  • homeId

    integer

    required

    The unique id for a home.

  • moduleId

    string

    required

    The unique id for a smart module.

  • collectionId

    string

    required

    Collection ID. It must be unique per home.

Request Headers What's this?
  • Authorization

    required

    Must contain a user or project API key.

Response
  • 200The requested time range is returned.
  • 401Authorization is required to access this resource.
  • 403Request failed because of denied permission.
  • 404The requested timeRange does not exist or is not accessible.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Response Body Sample

{
  "seriesId": "room1-temperature",
  "begin": "2018-12-11T17:00:22Z",
  "end": "2020-01-29T01:26:08.101Z"
}