Quickstart

Introduction


In this article, we will look at how to get time series data from the platform, what API endpoints to use, and what data to use to run API queries.


Authorization

First of all, you need to log in to the Cital Insights platform


Authorization with REST API endpoints

https://iot.cital.io/swagger-ui/#/login-endpoint/loginPost

https://iot.cital.io/swagger-ui/#/auth-controller/getUserUsingGET


Authorization with ThingsBoard REST client

from tb_rest_client.rest_client_ce import *

# Cital Insights REST API URL
url = "https://iot.cital.io:443"
# User credentials
username = "username@mail.com"
password = "user_password"

# Creating the REST client object with context manager to get auto token refresh
with RestClientCE(base_url=url) as rest_client:
        
    # Auth with credentials
    rest_client.login(username=username, password=password)
    # Get user info
    current_user = rest_client.get_user()



Entity view data

After authorization, the entity view data can be fetched with the entity view controller. You should use the entity type and the entity ID for further actions.


Get entity view data with REST API endpoints

https://iot.cital.io/swagger-ui/#/entity-view-controller/getCustomerEntityViewsUsingGET


Get entity view data with ThingsBoard REST client

...
    # Get entity view data
    customer_id = current_user.customer_id.id
    entity_view_data = rest_client.get_customer_entity_views(
        customer_id=current_user.customer_id.id, page=0, page_size=10)


Time-series data

We need to prepare some data for the next request. Dates should be converted to timestamp format. You can read about it here:  How to convert a date to a UTC timestamp? Then EntityViewID object should be created.


Get telemetry data with REST API endpoints

https://iot.cital.io/swagger-ui/#/telemetry-controller/getTimeseriesUsingGET


Get telemetry data with the ThingsBoard REST client

import datetime

...
    # Get time-series data
    start_ts = datetime_to_timestamp(datetime.datetime(2023, 2, 14, 0, 0, 0))
    end_ts = datetime_to_timestamp(datetime.datetime(2023, 2, 15, 0, 0, 0))
    entity_view_id = EntityViewId(
        id=entity_view_data.data[0].id.id,
        entity_type=entity_view_data.data[0].id.entity_type)
    
    telemetry_data = rest_client.get_timeseries(
        entity_id=entity_view_id, keys="tempOffBoard,waterPotOffBoard", start_ts=start_ts,
        end_ts=end_ts)



Import to CSV format


If you want to import downloaded data to CSV format you can use the code snippet below. We are using pandas library for the implementation of this code.

import pandas as pd

...
    # First create individual Dataframes for each time series
    tempOnBoard_df = pd.DataFrame(
        telemetry_data["tempOffBoard"]).set_index("ts").astype(float)
    waterPotOffBoard_df =pd.DataFrame(
        telemetry_data["waterPotOffBoard"]).set_index("ts").astype(float)
    # Merge all Single Dataframes
    final_df = pd.concat([tempOnBoard_df, waterPotOffBoard_df], join='outer', axis=1)
    final_df.columns = ["tempOnBoard", "waterPotOffBoard"]
    print(final_df.head())
    # Easy CSV export possible
    final_df.to_csv("downloaded_ts_data.csv")





Preview
0 of 0

General Inquiries

Working with Cital Insights

Soil Sensor Handling

Orders & Shipping

Data Collection & Gateways

API Documentation

User Tiers

Have a question?

Send us a message