Skip to content

Download Timeseries

Available Guides

Reference:

Field Description
resource Asset / Data Stream pair in KRN format. The KRN format is krn:ad:<asset_name>/<data_stream_name>
payload The data value
timestamp Exact UTC time when the data value was recorded, formatted in ISO 8601.
data_type Type of data stored, such as number, string, or boolean.
source User, Workload or Application that created the data in the Cloud
fields The field name keys for the data saved. By default this is just value
created UTC time when the data was created, formatted in ISO 8601.
updated UTC time when any of the data information was updated, formatted in ISO 8601.

Download Raw Timeseries Data

You can only download the timeseries data in a CSV file. See the next section below on how to do that.

API cURL Example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
curl -X "POST" \
  "https://<url.kelvin.ai>/api/v4/timeseries/range/get" \
  -H "Authorization: Bearer <Your Current Token>" \
  -H "Accept: application/x-json-stream" \
  -H "Content-Type: application/json" \
  -d '{
        "start_time": "2024-04-18T12:00:00.000000Z",
        "end_time": "2024-04-19T12:00:00.000000Z",
        "selectors": [
          { 
            "resource": "krn:ad:pcp_01/casing_pressure" 
          }
        ]
      }'

You will receive a response body with a status code of 200, indicating a successful operation.

For example, the response body might look like this:

API cURL Example Response
 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
[
   {
      "resource":"krn:ad:pcp_01/casing_pressure",
      "payload":9.207480441058955,
      "timestamp":"2024-04-18T12:00:00.000000Z"
   },
   {
      "resource":"krn:ad:pcp_01/casing_pressure",
      "payload":10.558049248009134,
      "timestamp":"2024-04-18T13:00:00.000000Z"
   },
   {
      "resource":"krn:ad:pcp_01/casing_pressure",
      "payload":10.213212569176205,
      "timestamp":"2024-04-18T14:00:00.000000Z"
   },
   {
      "resource":"krn:ad:pcp_01/casing_pressure",
      "payload":10.550493801775435,
      "timestamp":"2024-04-18T15:00:00.000000Z"
   },
   {
      "resource":"krn:ad:pcp_01/casing_pressure",
      "payload":8.934414753917585,
      "timestamp":"2024-04-18T16:00:00.000000Z"
   }
]

We will convert the information into a Pandas DataFrame.

API Client (Python) Example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
from kelvin.api.client import Client

# Login
client = Client(url="https://<url.kelvin.ai>", username="<your_username>")
client.login(password="<your_password>")

# Get Time Series Data
response = client.timeseries.get_timeseries_range(
    data={
        "start_time": "2024-12-16T12:00:00.000000Z",
        "end_time": "2024-12-18T12:00:00.000000Z",
        "selectors": [
            {
                "resource": "krn:ad:pcp_01/casing_pressure",
            }
        ]
    }
)

# Convert the response into a Pandas DataFrame
df = response.to_df(datastreams_as_column=True)

# Print the result
print(df)

The response will look something like this;

API Client (Python) Example Response
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
datastream_name                        timestamp asset_name  casing_pressure
0               2024-12-16 12:00:04.186969+00:00     pcp_01        55.595757
1               2024-12-16 12:00:09.163840+00:00     pcp_01        55.594723
2               2024-12-16 12:00:14.197772+00:00     pcp_01        55.594723
3               2024-12-16 12:00:19.298752+00:00     pcp_01        55.583904
4               2024-12-16 12:00:24.277415+00:00     pcp_01        55.583904
...                                          ...        ...              ...
34127           2024-12-18 11:30:39.200059+00:00     pcp_01        55.634033
34128           2024-12-18 11:30:44.170291+00:00     pcp_01        55.635864
34129           2024-12-18 11:30:49.214021+00:00     pcp_01        55.635864
34130           2024-12-18 11:30:54.382963+00:00     pcp_01        55.630901
34131           2024-12-18 11:30:59.105374+00:00     pcp_01        55.630901

[34132 rows x 3 columns]

Download Raw Timeseries Data to CSV file

You can download a range of data from the Data Explorer page.

To do this go to the Data Explorer page.

Select the Asset.

Select one or more Data Streams that you want to download.

Note

You have the ability to also aggregate data on the Data Explorer before downloading.

To aggregate, click on the Edit Aggregation button and select the aggregation for the target Data Stream.

Aggregations options; Average, Count, Maximum, Minimum, or Sum over a selected intervals.

Warning

The system will make every effort to follow the aggregations selected.

Only under extreme conditions, such as selecting minute intervals over a two-day range, the system may automatically adjust the interval to prevent large data updates that could freeze the browser.

Choose a time period.

Then click on the download button.

Select the Export Data option.

And finally confirm the download by clicking on the Okay button.

API cURL Example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
curl -X "POST" \
  "https://<url.kelvin.ai>/api/v4/timeseries/range/download" \
  -H "Authorization: Bearer <Your Current Token>" \
  -H "Accept: text/csv" \
  -H "Content-Type: application/json" \
  -d '{
        "start_time": "2024-04-18T12:00:00.000000Z",
        "end_time": "2024-04-19T12:00:00.000000Z",
        "selectors": [
          {
            "resource": "krn:ad:pcp_01/casing_pressure"
          }
        ]
      }' > data.csv

The data.csv file will look something like this;

Sample Downloaded Timeseries Data CSV File
1
2
3
resource,time,value
krn:ad:pcp_01/casing_pressure,2024-04-18T15:00:00.000000Z,11.768450335460644
krn:ad:pcp_01/casing_pressure,2024-04-18T16:00:00.000000Z,8.934414753917585

We will save the information into a CSV file.

API Client (Python) Example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
from kelvin.api.client import Client

# Login
client = Client(url="https://<url.kelvin.ai>", username="<your_username>")
client.login(password="<your_password>")

# Save Time Series Range of Data to CSV
response = client.timeseries.download_timeseries_range(
    data={
        "start_time": "2024-04-18T12:00:00.000000Z",
        "end_time": "2024-04-19T12:00:00.000000Z",
        "selectors": [
            {
                "resource": "krn:ad:pcp_01/casing_pressure"
            }
        ]
    }
)

# Open a file in write mode
with open('data.csv', 'w') as file:
    # Write the response to the file
    file.write(response)

The data.csv file will look something like this;

API Client (Python) Example Response
1
2
3
resource,time,value
krn:ad:pcp_01/casing_pressure,2024-04-18T15:00:00.000000Z,11.768450335460644
krn:ad:pcp_01/casing_pressure,2024-04-18T16:00:00.000000Z,8.934414753917585

Download Aggregated Timeseries Data

In Time Series API, you can download a range of data either in a raw format or aggregated format. The type of aggregation possible depends on the Data Type for the Asset / Data Stream pair.

Available Aggregations:

Data Type Aggregate Option Description
number none Raw data is returned
count Counts the number of values within each time bucket.
distinct Returns distinct values within each time_bucket bucket.
integral Calculates the area under the curve for each time_bucket bucket.
mean Calculates the average value within each time bucket.
median Finds the middle value in each time bucket.
mode Identifies the most frequently occurring value in each time time_bucket.
spread Represents the difference between the max and min values within each time time_bucket.
stddev Measures variation within each time time_bucket.
sum Adds up all the values within each time time_bucket.
string none Raw data is returned
count Counts the number of values within each time_bucket bucket.
distinct Returns distinct values within each time time_bucket.
mode Identifies the most frequently occurring value in each time time_bucket.

There are also the options to;

  • time_bucket: The window of data to aggregate, e.g. 5m, 1h (see https://golang.org/pkg/time/#ParseDuration for the acceptable formats)
  • time_shift: The offset for each window.
  • fill: allows you to fill missing points from a time bucket. It might be one of: none (default); null; linear (performs a linear regression); previous (uses the previous non-empty value); or an int.

In this example we will get the mean value per hour over a 24 hour period for an Asset / Data Stream pair. The Asset name is pcp_01 and the Data Stream name is casing_pressure.

You can download a range of data from the Data Explorer page.

To do this go to the Data Explorer page.

Select the Asset.

Select one or more Data Streams that you want to download.

Click on the Edit Aggregate button.

And then choose the type of aggregation you want for each Data Stream.

Warning

The system will make every effort to follow the aggregations selected.

Only under extreme conditions, such as selecting minute intervals over a two-day range, the system may automatically adjust the interval to prevent large data updates that could freeze the browser.

Note

If the aggregation option selected isNone, this means that the raw data will be used for the chart.

Check out the chapter on Raw Data View for more information about how raw data is displayed and when it is automatically aggregated.

This will affect the data exported to CSV.

Choose a time period.

Then click on the download button.

Select the Export Data option.

And finally confirm the download by clicking on the Okay button.

API cURL Example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
curl -X "POST" \
  "https://<url.kelvin.ai>/api/v4/timeseries/range/get" \
  -H "Authorization: Bearer <Your Current Token>" \
  -H "Accept: application/x-json-stream" \
  -H "Content-Type: application/json" \
  -d '{
        "start_time": "2024-04-17T12:00:00.000000Z",
        "end_time": "2024-04-18T12:00:00.000000Z",
        "selectors": [
          {
            "resource": "krn:ad:pcp_01/casing_pressure"
          }
        ],
        "agg": "mean",
        "fill": "none",
        "group_by_selector": True,
        "time_bucket": "1h",
        "time_shift": "1h"
      }'

You will receive a response body with a status code of 200, indicating a successful operation.

For example, the response body might look like this:

API cURL Example Response
 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
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
[
  {
    "resource": "krn:ad:pcp_01/casing_pressure",
    "payload": 55.81689687106529,
    "timestamp": "2024-04-17T01:00:00.000000Z",
  },
  {
    "resource": "krn:ad:pcp_01/casing_pressure",
    "payload": 55.802643852964586,
    "timestamp": "2024-04-18T01:00:00.000000Z",
  },
  {
    "resource": "krn:ad:pcp_01/casing_pressure",
    "payload": 55.65272958881385,
    "timestamp": "2024-04-19T01:00:00.000000Z",
  },
  {
    "resource": "krn:ad:pcp_01/casing_pressure",
    "payload": 55.672962275470624,
    "timestamp": "2024-04-20T01:00:00.000000Z",
  },
  {
    "resource": "krn:ad:pcp_01/casing_pressure",
    "payload": 55.79699800861461,
    "timestamp": "2024-04-21T01:00:00.000000Z",
  },
  {
    "resource": "krn:ad:pcp_01/casing_pressure",
    "payload": 55.75498124182507,
    "timestamp": "2024-04-22T01:00:00.000000Z",
  },
  {
    "resource": "krn:ad:pcp_01/casing_pressure",
    "payload": 55.71693869571614,
    "timestamp": "2024-04-23T01:00:00.000000Z",
  },
  {
    "resource": "krn:ad:pcp_01/casing_pressure",
    "payload": 55.93863554640519,
    "timestamp": "2024-04-24T01:00:00.000000Z",
  },
  {
    "resource": "krn:ad:pcp_01/casing_pressure",
    "payload": 59.94188689356177,
    "timestamp": "2024-04-25T01:00:00.000000Z",
  },
]

We will convert the information into a Pandas DataFrame.

API Client (Python) Example
 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
28
29
from kelvin.api.client import Client

# Login
client = Client(url="https://<url.kelvin.ai>", username="<your_username>")
client.login(password="<your_password>")

# Get Time Series Aggregated Range of Data
response = client.timeseries.get_timeseries_range(
    data={
        "start_time": "2024-04-17T12:00:00.000000Z",
        "end_time": "2024-04-25T12:00:00.000000Z",
        "selectors": [
            {
                "resource": "krn:ad:pcp_01/casing_pressure",
            }
        ],
        "agg": "mean",
        "fill": "none",
        "group_by_selector": True,
        "time_bucket": "24h",
        "time_shift": "1h",
    }
)

# Convert the response into a Pandas DataFrame
df = response.to_df()

# Print the result
print(df)

The response will look something like this;

API Client (Python) Example Response
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
    payload                       resource                 timestamp
0  55.816897  krn:ad:pcp_01/casing_pressure 2024-04-17 01:00:00+00:00
1  55.802644  krn:ad:pcp_01/casing_pressure 2024-04-18 01:00:00+00:00
2  55.652730  krn:ad:pcp_01/casing_pressure 2024-04-19 01:00:00+00:00
3  55.672962  krn:ad:pcp_01/casing_pressure 2024-04-20 01:00:00+00:00
4  55.796998  krn:ad:pcp_01/casing_pressure 2024-04-21 01:00:00+00:00
5  55.754981  krn:ad:pcp_01/casing_pressure 2024-04-22 01:00:00+00:00
6  55.716939  krn:ad:pcp_01/casing_pressure 2024-04-23 01:00:00+00:00
7  55.938636  krn:ad:pcp_01/casing_pressure 2024-04-24 01:00:00+00:00
8  59.941887  krn:ad:pcp_01/casing_pressure 2024-04-25 01:00:00+00:00