Timeseries

Time series is a core concept in Cognite and offers the possibility to extract datapoints at high performance for analytics or visualisation. To read more about time series and related datapoints, check out our concept description.

Get raw datapoints from a time series

There are two ways to get datapoints from a timeseries, either by the given name or by the int id that is automatically assigned by Cognite.

When looking up for name, you use the endpoint:

GET /api/0.5/projects/<project>/timeseries/data/
Host: api.cognitedata.com
api-key: <api-key>
1
2
3

If you want to simply get the raw data points attached to the time series, outside_temperature, you write:

GET /api/0.5/projects/<project>/timeseries/data/outside-temperature
Host: api.cognitedata.com
api-key: <api-key>
1
2
3

And you will get the response:

{
  "data": {
    "items": [
      {
        "name": "outside_temperature",
        "datapoints": [
          {
            "timestamp": 1533727936845,
            "value": 21.6
          },
          {
            "timestamp": 1533727950289,
            "value": 21.8
          },
          ...{
            "timestamp": 1533739764654,
            "value": 28.9
          },
          {
            "timestamp": 1533739777456,
            "value": 29.3
          }
        ]
      }
    ]
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

If you want to visualise or analyse a long time period, it could be useful to extract just the aggregate values between two time points. The query below returns the hourly average aggregate with ggranularity 1 hour, for the last 5 hours. The full list of available aggregates can be found in the API reference documentation. Start and end time can also be specified in UNIC epoch milliseconds.

GET /api/0.5/projects/<project>/timeseries/data/outside_temperature?aggregates=avg&granularity=1h&start=5h-ago&end=now
Host: api.cognitedata.com
api-key: <api-key>
1
2
3

The response is:

{
  "data": {
    "items": [
      {
        "name": "outside_temperature",
        "datapoints": [
          {
            "timestamp": 1542452400000,
            "average": 15.133800861111105
          },
          {
            "timestamp": 1542456000000,
            "average": 14.286872172746543
          },
          ...{
            "timestamp": 1542466800000,
            "average": 11.290880027777767
          },
          {
            "timestamp": 1542470400000,
            "average": 11.047296781864254
          }
        ]
      }
    ]
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

Get a dataframe

When building a machine learning model, or doing analytics in general, it is very useful to get all data required for the analysis in a dataframe, where the time stamps are aligned for all timeseries. Cognite offers that possibility through the endpoint, returning the data in CSV:

POST /api/0.5/projects/<project>/timeseries/dataframe
Host: api.cognitedata.com
api-key: <api-key>
1
2
3

To get the

{
  "start": "5h-ago",
  "end": "now",
  "aggregates": ["avg"],
  "granularity": "1h",
  "items": [
    {
      "name": "inside_temperature"
    },
    {
      "name": "outside_temperature"
    }
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14

The CSV response will then be:

timestamp inside_temperature outside_temperature
1542452400000 15.133800861111105 -0.4
1542456000000 14.286872172746543 -0.3
1542459600000 13.704991396697892 -0.3
1542463200000 12.409083402777783 -0.3
1542466800000 11.290880027777767 -0.25
1542470400000 11.004871248409353 -0.3

If any of the time series are missing data from a given period, it will return empty cells. One can also ask for multiple aggregates as count, variance, min or max that can be included in the same data frame. All available aggregates and granularities can be found in (api documentation)[https://doc.cognitedata.com/0.5].

Last Updated: 11/19/2018, 8:32:21 AM