Statistics Service

Last Updated on : 2024-06-05 03:15:10download

API list

API endpoint Description
statistics.allType Get the types of statistics supported by a device.
statistics.total Get all historical data.
statistics.minutes Get statistics calculated by minutes.
statistics.hours Get statistics calculated by hours.
statistics.days Get cumulative data by days.
statistics.weeks Get cumulative data by weeks.
statistics.months Get cumulative data by months.

Get types of statistics supported by a device

API description

Get the types of statistics supported by a device.

API endpoint

action:  statistics.allType

This API request requires the specific product configuration. Submit a service ticket with the product-associated account. The service ticket must include the product ID (PID) and the data point (DP) ID that requires statistical features. Then, Tuya’s staff will configure the product with these features for you.

Request parameter

Parameter name Type Description Required
device_id String The device ID. Yes.
code String The identifier of a specified data point, depending on the product. No. All DPs are queried by default.

Sample request

{
	"action": "statistics.allType",
	"params": {
		"device_id":"vdevo158331135285058"
	}
}

Response parameter

Parameter name Type Description
code Integer The response code.
success Boolean Indicates whether the operation is successful. Valid values:
  • true: succeeded.
  • false: failed.
msg String The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result Object The types of statistics supported by dpCode.

Sample response

{
    "success": true,
    "t": 1562898798074,
    "result": [
        {
            "code": "sum_dp",
            "stat_type": "sum"
        },
        {
            "code": "avg_dp",
            "stat_type": "avg"
        }
    ]
}

Get cumulative value of historical data

API description

Get the cumulative value of historical data.

API endpoint

action:  statistics.total

Request parameter

Parameter name Type Description Required
device_id String The device ID. Yes
code String The identifier of a specified data point, depending on the product. Yes

Sample request

{
	"action": "statistics.total",
	"params": {
		"device_id":"vdevo158331135285058",
		"code":"electricity"
	}
}

Response parameter

Parameter name Type Description
code Integer The response code.
success Boolean Indicates whether the operation is successful. Valid values:
  • true: succeeded.
  • false: failed.
msg String The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result Object The returned result.

Description of result

Parameter name Type Description
total String The statistics of cumulative data.

Sample response

{
    "success": true,
    "t": 1545286977957,
    "result": {
        "total" : "92.68"
    }
}

Get statistics calculated by minutes

API description

Query the status statistics of a device in the most recent seven days and get the statistics calculated at an interval of 15 minutes on each day.

API endpoint

action: statistics.quarters

Request parameter

Parameter name Type Description Required
device_id String The device ID. Yes
code String The identifier of a specified data point, depending on the product. Yes
start_quarter String The start minute of the period to be queried.
Format: yyyyMMddHHmm.
Yes
end_quarter String The end minute of the period to be queried. The value must be on the same date of start_minute and later than start_minute.
Format: yyyyMMddHHmm.
Yes

Sample request

{
	"action": "statistics.quarters",
	"params": {
		"device_id":"vdevo158331135285058",
		"code":"electricity",
		"start_quarter":"202003020815",
		"end_quarter":"202003021045"
	}
}

Response parameter

Parameter name Type Description
code Integer The response code.
success Boolean Indicates whether the operation is successful. Valid values:
  • true: succeeded.
  • false: failed.
msg String The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result Object The success callback.

Sample response

{
    "success": true,
    "t": 1567079117639,
    "result": {
        "quarters": {
            "202003020815": "0.01",
            "202003020830": "0.00",
            "202003020845": "0.01",
            "202003020900": "0.00",
            "202003020915": "0.01",
            "202003020930": "0.00",
            "202003020945": "0.01",
            "202003021000": "0.00",
            "202003021015": "0.02",
            "202003021030": "0.00"
        }
    }
}

Get statistics calculated by hours

API description

Query the status statistics of a device in the most recent seven days and get the statistics calculated at an interval of one hour on each day.

API endpoint

action: statistics.hours

Request parameter

Parameter name Type Description Required
device_id String The device ID. Yes
code String The identifier of a specified data point, depending on the product. Yes
start_hour String The start hour of the period to be queried.
Format: yyyyMMddHH.
Yes
end_hour String The end hour of the period to be queried. The value must be on the same date of start_hour and later than start_hour.
Format: yyyyMMddHH.
Yes
stat_type String The type of statistics. Valid values: sum, count, and avg. Default value: sum. Yes

Sample request

{
	"action": "statistics.hours",
	"params": {
		"device_id":"vdevo158331135285058",
		"code":"electricity",
		"start_hour":"2020030100",
		"end_hour":"2020030123"
	}
}

Response parameter

Parameter name Type Description
code Integer The response code.
success Boolean Indicates whether the operation is successful. Valid values:
  • true: succeeded.
  • false: failed.
msg String The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result Object The success callback.

Sample response

{
    "success": true,
    "t": 1562747403791,
    "result": {
        "hours": {
            "2020030208": "0.00",
            "2020030209": "1.00",
            "2020030210": "1.00",
            "2020030211": "1.00",
            "2020030212": "1.00"
        }
    }
}

Get cumulative data by days

API description

Get cumulative data by days.

API endpoint

action: statistics.days

Request parameter

Parameter name Type Description Required
device_id String The device ID. Yes
code String The identifier of a specified data point, depending on the product. Yes
start_day String The start date. Example: 20200225. Yes
end_day String The end date. Example: 20200302. Yes
stat_type String (Optional) The type of statistics. Default value: sum. No

Sample request

{
	"action": "statistics.days",
	"params": {
		"device_id":"vdevo158331135285058",
		"code":"electricity",
		"start_day":"20200225",
		"end_day":"20200302"
	}
}

Response parameter

Parameter name Type Description
code Integer The response code.
success Boolean Indicates whether the operation is successful. Valid values:
  • true: succeeded.
  • false: failed.
msg String The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result Object The returned result.

Description of result

Parameter name Type Description
days Map The daily statistics.

Sample response

{
    "success": true,
    "t": 1547650028453,
    "result": {
        "days": {
            "20200225": "0",
            "20200226": "0",
            "20200227": "0",
            "20200228": "0",
            "20200229": "0",
            "20200301": "0",
            "20200302": "0"
        }
    }
}

Get cumulative data by weeks

API description

Get cumulative data by weeks.

API endpoint

action: statistics.weeks

Request parameter

Parameter name Type Description Required
device_id String The device ID. Yes
code String The identifier of a specified data point, depending on the product. Yes
start_week String The start week. Example: 202005 to represent the fifth week of 2020. Yes
end_week String The end week. Example: 202007 to represent the seventh week of 2020. Yes

Sample request

{
	"action": "statistics.weeks",
	"params": {
		"device_id":"vdevo158331135285058",
		"code":"electricity",
		"start_week":"202005",
		"end_week":"202007"
	}
}

Response parameter

Parameter name Type Description
code Integer The response code.
success Boolean Indicates whether the operation is successful. Valid values:
  • true: succeeded.
  • false: failed.
msg String The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result Object The returned result.

Description of result

Parameter name Type Description
weeks Map The weekly statistics.

Sample response

{
    "success": true,
    "t": 1547650180271,
    "result": {
        "weeks": {
            "202005": "0",
            "202006": "0.02",
            "202007": "0"
        }
    }
}

Get cumulative data by months

API description

Get cumulative data by months.

API endpoint

action: statistics.months

Request parameter

Parameter name Type Description Required
device_id String The device ID. Yes
code String The identifier of a specified data point, depending on the product. Yes
start_month String The start month. Example: 202001. Yes
end_month String The end month. Example: 202003. Yes

The start month and end month must be in the same year.

Sample request

{
	"action": "statistics.months",
	"params": {
		"device_id":"vdevo158331135285058",
		"code":"electricity",
		"start_month":"202001",
		"end_month":"202003"
	}
}

Response parameter

Parameter name Type Description
code Integer The response code.
success Boolean Indicates whether the operation is successful. Valid values:
  • true: succeeded.
  • false: failed.
msg String The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result Object The returned result.

Description of result

Parameter name Type Description
months Map The monthly statistics.

Sample response

{
    "success": true,
    "t": 1545286977957,
    "result": {
        "months" : {
            "202001":"11.36",
            "202002":"13.81",
            "202003":"12.39",
        }
    }
}

Get cumulative values of target DP

API description

Get the cumulative value of a target DP.

API endpoint

action: statistics.all

Request parameter

Parameter name Type Description Required
device_id String The device ID. Yes
code String The identifier of a specified data point, depending on the product. Yes

Sample request

{
	"action": "statistics.all",
	"params": {
		"device_id":"vdevo158331135285058",
		"code":"electricity"
	}
}

Response parameter

Parameter name Type Description
code Integer The response code.
success Boolean Indicates whether the operation is successful. Valid values:
  • true: succeeded.
  • false: failed.
msg String The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result Object The returned result.

Description of result

Parameter name Type Description
this_day String The value of the current day.
sum String The cumulative value.
years Object The annual statistics. The result is returned by months of the year.

Sample response

{
    "result": {
        "sum": "0.00",
        "thisDay": "0.0",
        "years": {
            "2020": {
                "03": "0.00"
            }
        }
    },
    "success": true,
    "t": 1583156170485
}