Endpoint Time Series service

Base URL: https://cloud.kaaiot.com/epts/api/v1

  • host: required(string - default: localhost)
  • schema: required(one of http, https - default: http)
Time series
get
get

Returns configurations of all time series in application(s).

Time series data
get post
get

Returns the most recent time series data.

post

Returns the most recent time series data.

Returns the most recent time series data.

Secured by OAuth 2.0 with scopes:
  • endpoint:read
  • time-series:read

EPTS supports OAuth 2.0 for authenticating all API requests.

URI Parameters

  • applicationName: required(string)

    Application name

    Example:

    clpg49rtl4es7380a2bg

Query Parameters

  • endpointId: (string)

    Zero or more endpoint ID(s). If not specified, data is returned for all available endpoints.

    Example:

    2ebaf0ab-76f3-4211-a27f-af310be8987f,8b4aec8a-0a13-4b92-ba0b-0a39cfd5e297
  • timeSeriesName: (string)

    One or more time series name(s).

    Example:

    temperature,humidity
  • beforeDate: (datetime)

    ISO-8601 encoded time before which to retrieve data points. Relative time range is supported by using now keyword. Supported time units are s, m, h, d, w, M and y. now can be used directly or with subtracting time value, such as now-3d.

    Example:

    2017-04-20T12:00:00.000Z
  • offset: (integer - default: 0)

    The starting index of data point from which the server should return data.

    Example:

    10
  • limit: (integer - default: 1)

    The maximum number of data points to be returned.

    Example:

    2

HTTP status code 200

Arrays of most recent data points mapped by time series names and endpoint IDs. Each data point contains ingestionTimestamp (ISO 8601, UTC) — the server-assigned time when the data point was ingested by the platform, timestamp — the time of the measurement, and values — a map of named values.

Body

Media type: application/json

Type: object

Example:

{
  "2ebaf0ab-76f3-4211-a27f-af310be8987f": {
    "temperature": [
      {
        "ingestionTimestamp": "2017-04-20T11:19:58.000Z",
        "timestamp": "2017-04-20T11:19:57.848Z",
        "values": {
          "value": 20.2,
          "lat": 40.766892,
          "lon": -74.344482
        }
      }
    ],
    "humidity": [
      {
        "ingestionTimestamp": "2017-04-20T11:19:58.000Z",
        "timestamp": "2017-04-20T11:19:57.848Z",
        "values": {
          "value": 63,
          "lat": 40.766892,
          "lon": -74.344482
        }
      }
    ]
  },
  "8b4aec8a-0a13-4b92-ba0b-0a39cfd5e297": {
    "temperature": [
      {
        "ingestionTimestamp": "2017-04-20T11:19:58.000Z",
        "timestamp": "2017-04-20T11:19:57.848Z",
        "values": {
          "value": 23.1,
          "lat": 40.766892,
          "lon": -74.344482
        }
      }
    ],
    "humidity": [
      {
        "ingestionTimestamp": "2017-04-20T11:19:58.000Z",
        "timestamp": "2017-04-20T11:19:57.848Z",
        "values": {
          "value": 75,
          "lat": 40.766892,
          "lon": -74.344482
        }
      }
    ]
  }
}

Secured by OAuth 2.0

Headers

  • Authorization: (string)

    Used to send a valid OAuth 2 access token. Example: "Authorization: Bearer 'access_token'" where 'access_token' must be replaced by a valid OAuth access token. This header is needed only if API authentication is enabled for the service.

Returns the most recent time series data.

Secured by OAuth 2.0 with scopes:
  • endpoint:read
  • time-series:read

EPTS supports OAuth 2.0 for authenticating all API requests.

URI Parameters

  • applicationName: required(string)

    Application name

    Example:

    clpg49rtl4es7380a2bg

Body

Media type: application/json

Type: object

Properties
  • timeSeriesNames: (array of string)

    One or more time series names.

  • beforeDate: (datetime)

    ISO-8601 encoded end time to retrieve data points to. Relative time range is supported by using now keyword. Supported time units are s, m, h, d, w, M and y. now can be used directly or with subtracting time value, such as now-3d.

  • offset: (number)

    Number of data points to skip from the most recent data point.

  • limit: (number)

    Maximum number of data points to return.

  • endpointIDs: (array of string)

    Zero or more endpoint IDs. If not specified, data is returned for all available endpoints.

Example:

{
  "timeSeriesNames": [
    "temperature",
    "humidity"
  ],
  "beforeDate": "2019-01-01T00:00:00Z",
  "offset": 10,
  "limit": 5,
  "endpointIDs": [
    "2ebaf0ab-76f3-4211-a27f-af310be8987f",
    "8b4aec8a-0a13-4b92-ba0b-0a39cfd5e297"
  ]
}

HTTP status code 200

Arrays of most recent data points mapped by time series names and endpoint IDs. Each data point contains ingestionTimestamp (ISO 8601, UTC) — the server-assigned time when the data point was ingested by the platform, timestamp — the time of the measurement, and values — a map of named values.

Body

Media type: application/json

Type: object

Example:

{
  "2ebaf0ab-76f3-4211-a27f-af310be8987f": {
    "temperature": [
      {
        "ingestionTimestamp": "2017-04-20T11:19:58.000Z",
        "timestamp": "2017-04-20T11:19:57.848Z",
        "values": {
          "value": 20.2,
          "lat": 40.766892,
          "lon": -74.344482
        }
      }
    ],
    "humidity": [
      {
        "ingestionTimestamp": "2017-04-20T11:19:58.000Z",
        "timestamp": "2017-04-20T11:19:57.848Z",
        "values": {
          "value": 63,
          "lat": 40.766892,
          "lon": -74.344482
        }
      }
    ]
  },
  "8b4aec8a-0a13-4b92-ba0b-0a39cfd5e297": {
    "temperature": [
      {
        "ingestionTimestamp": "2017-04-20T11:19:58.000Z",
        "timestamp": "2017-04-20T11:19:57.848Z",
        "values": {
          "value": 23.1,
          "lat": 40.766892,
          "lon": -74.344482
        }
      }
    ],
    "humidity": [
      {
        "ingestionTimestamp": "2017-04-20T11:19:58.000Z",
        "timestamp": "2017-04-20T11:19:57.848Z",
        "values": {
          "value": 75,
          "lat": 40.766892,
          "lon": -74.344482
        }
      }
    ]
  }
}

Secured by OAuth 2.0

Headers

  • Authorization: (string)

    Used to send a valid OAuth 2 access token. Example: "Authorization: Bearer 'access_token'" where 'access_token' must be replaced by a valid OAuth access token. This header is needed only if API authentication is enabled for the service.

get post
get

Returns historical time series data within the specified time range. Each data point in the response contains ingestionTimestamp (ISO 8601, UTC) — the server-assigned time when the data point was ingested by the platform.

post

Returns historical time series data within the specified time range. Each data point in the response contains ingestionTimestamp (ISO 8601, UTC) — the server-assigned time when the data point was ingested by the platform.

Returns historical time series data within the specified time range. Each data point in the response contains ingestionTimestamp (ISO 8601, UTC) — the server-assigned time when the data point was ingested by the platform.

Secured by OAuth 2.0 with scopes:
  • endpoint:read
  • time-series:read

EPTS supports OAuth 2.0 for authenticating all API requests.

URI Parameters

  • applicationName: required(string)

    Application name

    Example:

    clpg49rtl4es7380a2bg

Query Parameters

  • timeSeriesName: required(string)

    One or more time series names.

    Example:

    temperature,humidity
  • endpointId: (string)

    Zero or more endpoint IDs. If not specified, data is returned for all available endpoints.

    Example:

    2ebaf0ab-76f3-4211-a27f-af310be8987f,8b4aec8a-0a13-4b92-ba0b-0a39cfd5e297
  • fromDate: required(datetime)

    ISO-8601 encoded start time to retrieve data points from. Relative time range is supported by using now keyword. Supported time units are s, m, h, d, w, M and y. now can be used directly or with subtracting time value, such as now-3d.

    Example:

    2017-04-20T00:00:00.000Z
  • toDate: required(datetime)

    ISO 8601 encoded end time to retrieve data points to. Relative time range is supported by using now keyword. Supported time units are s, m, h, d, w, M and y. now can be used directly or with subtracting time value, such as now-3d.

    Example:

    2017-04-22T00:00:00.000Z
  • includeTime: (one of from, to, both, none - default: none)

    Defines which of the fromDate and toDate are inclusive.

  • sort: (one of ASC, DESC - default: ASC)

    Sorting order by timestamp.

HTTP status code 200

Array of objects, each contains arrays of most recent data points mapped by time series names and endpoint IDs. The response is returned in chunks. Each chunk is guaranteed to contain an integer number of top-level array elements. The same endpoint ID (and time series name) may occur in several chunks (note an example of that below).

Body

Media type: application/json

Type: array of object

Example:

[
  {
    "2ebaf0ab-76f3-4211-a27f-af310be8987f":{
      "temperature":[
        {
          "ingestionTimestamp":"2017-04-20T11:19:58.000Z",
          "timestamp":"2017-04-20T11:19:57.848Z",
          "values":{
            "value":20.2,
            "lat":40.766892,
            "lon":-74.344482
          }
        },
        {
          "ingestionTimestamp":"2017-04-20T11:20:58.000Z",
          "timestamp":"2017-04-20T11:20:57.848Z",
          "values":{
            "value":20.7,
            "lat":40.766892,
            "lon":-74.344482
          }
        }
      ],
      "humidity":[
        {
          "ingestionTimestamp":"2017-04-20T11:19:58.000Z",
          "timestamp":"2017-04-20T11:19:57.848Z",
          "values":{
            "value":63,
            "lat":40.766892,
            "lon":-74.344482
          }
        }
      ]
    }
  },
  {
    "2ebaf0ab-76f3-4211-a27f-af310be8987f":{
      "temperature":[
        {
          "ingestionTimestamp":"2017-04-20T11:21:58.000Z",
          "timestamp":"2017-04-20T11:21:57.848Z",
          "values":{
            "value":20.9,
            "lat":40.766892,
            "lon":-74.344482
          }
        }
      ]
    },
    "8b4aec8a-0a13-4b92-ba0b-0a39cfd5e297":{
      "temperature":[
        {
          "ingestionTimestamp":"2017-04-20T11:19:58.000Z",
          "timestamp":"2017-04-20T11:19:57.848Z",
          "values":{
            "value":23.1,
            "lat":40.766892,
            "lon":-74.344482
          }
        },
        {
          "ingestionTimestamp":"2017-04-20T11:20:58.000Z",
          "timestamp":"2017-04-20T11:20:57.848Z",
          "values":{
            "value":22.8,
            "lat":40.766892,
            "lon":-74.344482
          }
        }
      ],
      "humidity":[
        {
          "ingestionTimestamp":"2017-04-20T11:19:58.000Z",
          "timestamp":"2017-04-20T11:19:57.848Z",
          "values":{
            "value":75,
            "lat":40.766892,
            "lon":-74.344482
          }
        }
      ]
    }
  }
]

Secured by OAuth 2.0

Headers

  • Authorization: (string)

    Used to send a valid OAuth 2 access token. Example: "Authorization: Bearer 'access_token'" where 'access_token' must be replaced by a valid OAuth access token. This header is needed only if API authentication is enabled for the service.

Returns historical time series data within the specified time range. Each data point in the response contains ingestionTimestamp (ISO 8601, UTC) — the server-assigned time when the data point was ingested by the platform.

Secured by OAuth 2.0 with scopes:
  • endpoint:read
  • time-series:read

EPTS supports OAuth 2.0 for authenticating all API requests.

URI Parameters

  • applicationName: required(string)

    Application name

    Example:

    clpg49rtl4es7380a2bg

Body

Media type: application/json

Type: object

Properties
  • timeSeriesNames: required(array of string)

    One or more time series names.

  • fromDate: required(datetime)

    ISO-8601 encoded start time to retrieve data points from. Relative time range is supported by using now keyword. Supported time units are s, m, h, d, w, M and y. now can be used directly or with subtracting time value, such as now-3d.

  • toDate: required(datetime)

    ISO 8601 encoded end time to retrieve data points to. Relative time range is supported by using now keyword. Supported time units are s, m, h, d, w, M and y. now can be used directly or with subtracting time value, such as now-3d.

  • sort: (one of ASC, DESC)

    Sorting order by timestamp.

  • includeTime: (one of from, to, both, none)

    Defines which of the fromDate and toDate are inclusive.

  • endpointIDs: (array of string)

    Zero or more endpoint IDs. If not specified, data is returned for all available endpoints.

Example:

{
  "timeSeriesNames": [
    "temperature",
    "humidity"
  ],
  "fromDate": "2019-01-01T00:00:00Z",
  "toDate": "2019-01-02T00:00:00Z",
  "sort": "DESC",
  "includeTime": "both",
  "endpointIDs": [
    "2ebaf0ab-76f3-4211-a27f-af310be8987f",
    "8b4aec8a-0a13-4b92-ba0b-0a39cfd5e297"
  ]
}

HTTP status code 200

Array of objects, each contains arrays of most recent data points mapped by time series names and endpoint IDs. The response is returned in chunks. Each chunk is guaranteed to contain an integer number of top-level array elements. The same endpoint ID (and time series name) may occur in several chunks (note an example of that below).

Body

Media type: application/json

Type: array of object

Example:

[
  {
    "2ebaf0ab-76f3-4211-a27f-af310be8987f":{
      "temperature":[
        {
          "ingestionTimestamp":"2017-04-20T11:19:58.000Z",
          "timestamp":"2017-04-20T11:19:57.848Z",
          "values":{
            "value":20.2,
            "lat":40.766892,
            "lon":-74.344482
          }
        },
        {
          "ingestionTimestamp":"2017-04-20T11:20:58.000Z",
          "timestamp":"2017-04-20T11:20:57.848Z",
          "values":{
            "value":20.7,
            "lat":40.766892,
            "lon":-74.344482
          }
        }
      ],
      "humidity":[
        {
          "ingestionTimestamp":"2017-04-20T11:19:58.000Z",
          "timestamp":"2017-04-20T11:19:57.848Z",
          "values":{
            "value":63,
            "lat":40.766892,
            "lon":-74.344482
          }
        }
      ]
    }
  },
  {
    "2ebaf0ab-76f3-4211-a27f-af310be8987f":{
      "temperature":[
        {
          "ingestionTimestamp":"2017-04-20T11:21:58.000Z",
          "timestamp":"2017-04-20T11:21:57.848Z",
          "values":{
            "value":20.9,
            "lat":40.766892,
            "lon":-74.344482
          }
        }
      ]
    },
    "8b4aec8a-0a13-4b92-ba0b-0a39cfd5e297":{
      "temperature":[
        {
          "ingestionTimestamp":"2017-04-20T11:19:58.000Z",
          "timestamp":"2017-04-20T11:19:57.848Z",
          "values":{
            "value":23.1,
            "lat":40.766892,
            "lon":-74.344482
          }
        },
        {
          "ingestionTimestamp":"2017-04-20T11:20:58.000Z",
          "timestamp":"2017-04-20T11:20:57.848Z",
          "values":{
            "value":22.8,
            "lat":40.766892,
            "lon":-74.344482
          }
        }
      ],
      "humidity":[
        {
          "ingestionTimestamp":"2017-04-20T11:19:58.000Z",
          "timestamp":"2017-04-20T11:19:57.848Z",
          "values":{
            "value":75,
            "lat":40.766892,
            "lon":-74.344482
          }
        }
      ]
    }
  }
]

Secured by OAuth 2.0

Headers

  • Authorization: (string)

    Used to send a valid OAuth 2 access token. Example: "Authorization: Bearer 'access_token'" where 'access_token' must be replaced by a valid OAuth access token. This header is needed only if API authentication is enabled for the service.

post
post

Deletes series from application.

Deletes series from application.

Secured by OAuth 2.0 with scopes:
  • application:timeseries-config:delete

EPTS supports OAuth 2.0 for authenticating all API requests.

URI Parameters

  • applicationName: required(string)

    Application name

    Example:

    clpg49rtl4es7380a2bg

Body

Media type: application/json

Type: object

Properties
  • timeSeriesNames: (array of string)

    One or more time series names.

Example:

{
  "timeSeriesNames": [
    "temperature",
    "humidity",
    "location"
  ]
}

HTTP status code 204

Series successfully deleted.

Secured by OAuth 2.0

Headers

  • Authorization: (string)

    Used to send a valid OAuth 2 access token. Example: "Authorization: Bearer 'access_token'" where 'access_token' must be replaced by a valid OAuth access token. This header is needed only if API authentication is enabled for the service.

post
post

Retrieves a paginated list of the latest time series data records.

Retrieves a paginated list of the latest time series data records.

Secured by OAuth 2.0 with scopes:
  • endpoint:read
  • time-series:read

EPTS supports OAuth 2.0 for authenticating all API requests.

URI Parameters

  • applicationName: required(string)

    Application name

    Example:

    clpg49rtl4es7380a2bg
  • endpointID: required(string)

    Endpoint ID

    Example:

    2ebaf0ab-76f3-4211-a27f-af310be8987f

Query Parameters

  • fromDate: (datetime)

    ISO-8601 encoded start time to retrieve data points from. Relative time is supported by using now keyword. Supported time units are s, m, h, d, w, M and y. now can be used directly or with subtracting time value, such as now-3d.

  • offsetDate: (datetime)

    The reference point in time for pagination, used to skip records after this time. Relative time is supported by using now keyword. Supported time units are s, m, h, d, w, M and y. now can be used directly or with subtracting time value, such as now-3d.

  • limit: (number)

    Maximum number of data points to return.

Body

Media type: application/json

Type: object

Properties
  • timeSeriesNames: (array of string)

    One or more time series names.

Example:

{
  "timeSeriesNames": [
    "temperature",
    "humidity",
    "location"
  ]
}

HTTP status code 200

Time series data records successfully retrieved.

Body

Media type: application/json

Type: object

Properties
  • data: required(array of object)

    List of time series data points records.

    Items:

    • hasNextPage: required(boolean)

      If hasNextPage is true, use the nextPageOffsetDate to request the next page.

    • nextPageOffsetDate: (datetime)

      ISO-8601 encoded time to skip records after this point for pagination.

    Example:

    {
  "data": [
    {
      "timestamp": "2017-04-20T11:19:57.848Z",
      "temperature": 60.2,
      "humidity": 88,
      "location": {
        "lat": 40.766892,
        "lon": -74.344482
      }
    },
    {
      "timestamp": "2017-04-20T11:19:56.932Z",
      "humidity": 75
    },
    {
      "timestamp": "2017-04-20T11:19:55.534Z",
      "temperature": 20.2
    }
  ],
  "hasNextPage": true,
  "nextPageOffsetDate": "2017-04-20T11:19:55.534Z"
}

    Secured by OAuth 2.0

    Headers

    • Authorization: (string)

      Used to send a valid OAuth 2 access token. Example: "Authorization: Bearer 'access_token'" where 'access_token' must be replaced by a valid OAuth access token. This header is needed only if API authentication is enabled for the service.

    post
    post

    Deletes time series data within a specified time range.

    Deletes time series data within a specified time range.

    Secured by OAuth 2.0 with scopes:
    • endpoint:update
    • time-series:delete

    EPTS supports OAuth 2.0 for authenticating all API requests.

    URI Parameters

    • applicationName: required(string)

      Application name

      Example:

      clpg49rtl4es7380a2bg
    • endpointID: required(string)

      Endpoint ID

      Example:

      2ebaf0ab-76f3-4211-a27f-af310be8987f

    Query Parameters

    • fromDate: required(datetime)

      ISO-8601 encoded start time to retrieve data points from. Relative time is supported by using now keyword. Supported time units are s, m, h, d, w, M and y. now can be used directly or with subtracting time value, such as now-3d.

    • toDate: required(datetime)

      ISO-8601 encoded end time to retrieve data points from. Relative time is supported by using now keyword. Supported time units are s, m, h, d, w, M and y. now can be used directly or with subtracting time value, such as now-3d.

    Body

    Media type: application/json

    Type: object

    Properties
    • timeSeriesNames: (array of string)

      One or more time series names.

    Example:

    {
  "timeSeriesNames": [
    "temperature",
    "humidity",
    "location"
  ]
}

    HTTP status code 204

    Time series data successfully deleted.

    Secured by OAuth 2.0

    Headers

    • Authorization: (string)

      Used to send a valid OAuth 2 access token. Example: "Authorization: Bearer 'access_token'" where 'access_token' must be replaced by a valid OAuth access token. This header is needed only if API authentication is enabled for the service.

    Time series data by application version
    put
    put

    Updates time series data for the specified endpoints.

    Time series data structure must match the configured time series definition (explicit JSON null values are permitted for any data point value). Data points with the same timestamp are re-writen on subsequent updates.

    Updates time series data for the specified endpoints.

    Time series data structure must match the configured time series definition (explicit JSON null values are permitted for any data point value). Data points with the same timestamp are re-writen on subsequent updates.

    Secured by OAuth 2.0 with scopes:
    • endpoint:update

    EPTS supports OAuth 2.0 for authenticating all API requests.

    URI Parameters

    • appVersionName: required(string)

      Application version name

      Example:

      0327fc40-7ac1-4ad0-8a5f-f352e69fcda7-v1

    Body

    Media type: application/json

    Type: Map of endpoint IDs to their time series. Each time series represented as a map of time series name to the array of data poins. A data point is a data structure consisting of a `timestamp` and one or more named `values`. The `timestamp` is in ISO 8601 format (UTC timezone). Data point values can be of an arbitrary primitive or a composite data type.

    Example:

    {
  "2ebaf0ab-76f3-4211-a27f-af310be8987f": {
    "temperature": [
      {
        "timestamp": "2017-04-20T11:19:57.848Z",
        "values": {
          "value": 20.2,
          "lat": 40.766892,
          "lon": -74.344482
        }
      },
      {
        "timestamp": "2017-04-20T11:20:57.848Z",
        "values": {
          "value": 20.7,
          "lat": 40.766892,
          "lon": -74.344482
        }
      }
    ],
    "humidity": [
      {
        "timestamp": "2017-04-20T11:19:57.848Z",
        "values": {
          "value": 63,
          "lat": 40.766892,
          "lon": -74.344482
        }
      }
    ]
  },
  "8b4aec8a-0a13-4b92-ba0b-0a39cfd5e297": {
    "temperature": [
      {
        "timestamp": "2017-04-20T11:19:57.848Z",
        "values": {
          "value": 23.1,
          "lat": 40.766892,
          "lon": -74.344482
        }
      },
      {
        "timestamp": "2017-04-20T11:20:57.848Z",
        "values": {
          "value": 22.8,
          "lat": 40.766892,
          "lon": -74.344482
        }
      }
    ],
    "humidity": [
      {
        "timestamp": "2017-04-20T11:19:57.848Z",
        "values": {
          "value": 75,
          "lat": 40.766892,
          "lon": -74.344482
        }
      }
    ]
  }
}

    HTTP status code 204

    Endpoints time series data successfully updated.

    HTTP status code 400

    Request is not valid (payload is not a JSON object, time series name is not valid, content does not match the time series definition, etc).

    HTTP status code 404

    Some of the requested endpoints are not found or the querying user is denied access.

    Secured by OAuth 2.0

    Headers

    • Authorization: (string)

      Used to send a valid OAuth 2 access token. Example: "Authorization: Bearer 'access_token'" where 'access_token' must be replaced by a valid OAuth access token. This header is needed only if API authentication is enabled for the service.