Get Datapoint Value

Purpose

This API lets you retrieve datapoint values of managed entities you monitor.

You can use it to:

Fetch historical data (time series) for charts and analysis.
Get a summarized current value (single value) by calculating an average, maximum, etc., over a specified time window.
Get customized data output by specifying the time range, grouping intervals (such as hourly or daily), and aggregation functions.

Request URL

Request method : POST

{api-domain}/iot/{version}/datapoints/data

Supported Modules

Supported Modules : Datapoints

Headers

Authorization: Zoho-oauthtoken {{oauth}}

Scope

ZohoIOT.modules.datapoints.data.CREATE

Request JSON

metrics- JSON Array, mandatory

metrics - The metric key is a JSON array, where each metric block contains a list of datapoint details along with its aggregation and other related parameters.

The datapoint details along with their aggregation and other related parameters that make up the array are provided below.

JSON Array Keys

datapoint_template_ids - array (long), optional

The list of datapoint template or definition IDs of a Managed Entity model for which time-series data needs to be retrieved.

Limitation - 5 datapoint template ids per block

datapoint_ids - array (long), optional

The list of datapoint instance IDs of a Managed Entity instance for which we need to get the timeseries data.

Limitation - 5 datapoint instance ids per block

datapoint_names - array (string), optional

If the datapoint IDs are not known, this parameter can be used to specify datapoint names for the model or instance. Indicate whether the names belong to a model or an instance by providing the corresponding model_name or instance_name key mentioned below.

instance_name - string, optional

To indicate the instance from which the datapoint names are derived.

Mandatory - If the datapoint_names are from instance, this key is mandatory.

model_name, string, optional

To indicate the model from which the datapoint names are derived.

Mandatory - If the datapoint_names are from model, this key is mandatory.

To use this API, specify either a datapoint template or a datapoint instance.

For a datapoint template, provide datapoint_template_ids or datapoint_names along with model_name
For a datapoint instance, provide datapoint_ids or datapoint_names along with instance_name.

aggregation, string, optional

The function to be used for aggregation.

Predefined Function - sum, avg, max, min, last_value, first_value

time_grouping - string, optional

To aggregate the datapoint values with the mentioned time group.

Predefined Grouping Values - hour, day, week, month

field_grouping - string,optional

To aggregate the datapoint values based on the managed entity's instance.

Predefined Grouping Values - instance

period - string,optional

To fetch the datapoint values based on this given period (Time Range)

Predefined Period Values - lasthour, last24hours, today, yesterday, thisweek, last7days, lastweek, thismonth, lastmonth, last30days, thisyear, lastyear, custom_range.

custom_range - json object,optional

To fetch the datapoint values based on a custom period.

Example Json Format:
{
"custom_range":{
"from": {
"value": "yyyy-MM-dd'T'HH:mm:ss"
},
"to": {
"value": "yyyy-MM-dd'T'HH:mm:ss"
}
}
}

sort_order - string,optional

To fetch the datapoint values based on order of timestamp or instance.

Predefined Sort Values - asc, desc

filter_by - object,optional

To filter either the Managed Entity records or Datapoint value.

Example 1: using criteria key you can filter the Managed Entity records connected to a particular gateway.
Example 2: using datapoint_criteria key you can filter the datapoint value greater than some value.

Format: The format for criteria is similar to the filter used in Custom View. Refer to the sample criteria format in the right column.

per_page - To set number of values per page

Example - If the per_page is given as 10 - Only 10 values of the specified datapoints will be returned in response

Default / Max value - 1500

Mandatory - No

page - To set the page number

Example - If the per_page is given as 10 and page is 2 - Returns 10 values of second page (11 - 20)

Mandatory - No

Endpoints

CopiedPOST/datapoints/data

Sample Request 1

Copied//Purpose : Getting the sum of values of <datapoint_name> for last year.

{
  "metrics": [
    {
      "datapoint_ids": [
        44000000166084
      ],
      "period":"lastyear",
      "aggregation":"sum"
    }
  ]
}

Sample Response 1

Copied{
    "data": {
        "result": [
            {
                "44000000166084": 545
            }
        ]
    },
    "info": {
        "per_page": 200,
        "count": 1,
        "page": 1,
        "more_records": false
    }
}

Sample Request 2

Copied//Purpose : Getting the sum of values of <datapoint_name> for last year grouped by month and sorted in descending order.

{
  "metrics": [
    {
      "datapoint_ids": [
        44000000166084,44000000166092
      ],
      "period":"lastyear",
      "time_grouping":"month",
      "sort_order" : "desc",
      "aggregation" : "sum"
    }
  ]
}

Sample Response 2

Copied{
  "data": {
    "result": [
      {
        "44000000166092": [
          {
            "timestamp": "1764527400000",
            "timestamp_string": "December"
          }
        ],
        "44000000166084": [
          {
            "value": 18,
            "timestamp": "1764527400000",
            "timestamp_string": "December"
          }
        ]
      }
    ]
  },
  "info": {
    "per_page": 200,
    "count": 3,
    "page": 1,
    "more_records": false
  }
}

Sample Criteria Format

Copied{
 "criteria":
 {
   "condition_text": "(1 AND 2)",
   "conditions": {
     "1": {
       "field": {
         "api_name": "name"
       },
       "comparator": "starts_with",
       "value": "AHU"
     },
     "2": {
       "field": {
         "api_name": "connected_gateway"
       },
       "comparator": "equal",
       "value": [
         {
           "id": "150000020566108",
           "name": "Apricot BMS AHU BacNet Polling Gateway"
         }
       ]
     }
   }
 }