Query Device's State

Query the current status of the device through device and sku.

example for lights and appliances

capabilities

{
      "sku": "H7143",
      "device": "BA:82:D4:AD:FC:94:A1:D8",
      "deviceName": "Smart Humidifier",
      "type": "devices.types.humidifier",
      "capabilities": [
        {
          "type": "devices.capabilities.on_off",
          "instance": "powerSwitch",
          "parameters": {
            "dataType": "ENUM",
            "options": [
              {
                "name": "on",
                "value": 1
              },
              {
                "name": "off",
                "value": 0
              }
            ]
          }
        },
        {
          "type": "devices.capabilities.toggle",
          "instance": "warmMistToggle",
          "parameters": {
            "dataType": "ENUM",
            "options": [
              {
                "name": "on",
                "value": 1
              },
              {
                "name": "off",
                "value": 0
              }
            ]
          }
        },
        {
          "type": "devices.capabilities.work_mode",
          "instance": "workMode",
          "parameters": {
            "dataType": "STRUCT",
            "fields": [
              {
                "fieldName": "workMode",
                "dataType": "ENUM",
                "options": [
                  {
                    "name": "Manual",
                    "value": 1
                  },
                  {
                    "name": "Auto",
                    "value": 3
                  }
                ],
                "required": true
              },
              {
                "fieldName": "modeValue",
                "dataType": "ENUM",
                "options": [
                  {
                    "name": "Manual",
                    "options": [
                      {
                        "value": 1
                      },
                      {
                        "value": 2
                      },
                      {
                        "value": 3
                      },
                      {
                        "value": 4
                      },
                      {
                        "value": 5
                      },
                      {
                        "value": 6
                      },
                      {
                        "value": 7
                      },
                      {
                        "value": 8
                      },
                      {
                        "value": 9
                      }
                    ]
                  },
                  {
                    "defaultValue": 0,
                    "name": "Auto"
                  }
                ],
                "required": false
              }
            ]
          }
        },
        {
          "type": "devices.capabilities.range",
          "instance": "humidity",
          "parameters": {
            "dataType": "INTEGER",
            "range": {
              "min": 40,
              "max": 80,
              "precision": 1
            }
          }
        },
        {
          "type": "devices.capabilities.toggle",
          "instance": "nightlightToggle",
          "parameters": {
            "dataType": "ENUM",
            "options": [
              {
                "name": "on",
                "value": 1
              },
              {
                "name": "off",
                "value": 0
              }
            ]
          }
        },
        {
          "type": "devices.capabilities.range",
          "instance": "brightness",
          "parameters": {
            "dataType": "INTEGER",
            "range": {
              "min": 1,
              "max": 100,
              "precision": 1
            }
          }
        },
        {
          "type": "devices.capabilities.color_setting",
          "instance": "colorRgb",
          "parameters": {
            "dataType": "INTEGER",
            "range": {
              "min": 0,
              "max": 16777215,
              "precision": 1
            }
          }
        },
        {
          "type": "devices.capabilities.mode",
          "instance": "nightlightScene",
          "parameters": {
            "dataType": "ENUM",
            "options": [
              {
                "name": "Forest",
                "value": 1
              },
              {
                "name": "Ocean",
                "value": 2
              },
              {
                "name": "Wetland",
                "value": 3
              },
              {
                "name": "Leisurely",
                "value": 4
              },
              {
                "name": "ASleep",
                "value": 5
              }
            ]
          }
        },
        {
          "type": "devices.capabilities.event",
          "instance": "lackWaterEvent",
          "alarmType": 51,
          "eventState": {
            "options": [
              {
                "name": "lackWater",
                "value": 1,
                "message": "Lack of Water"
              }
            ]
          }
        }
      ]
    },

request example

POST /router/api/v1/device/state HTTP/1.1
Host: https://openapi.api.govee.com
Content-Type: application/json
Govee-API-Key: xxxx

{
    "requestId": "uuid",
    "payload": {
        "sku": "H7143",
        "device": "52:8B:D4:AD:FC:45:5D:FE"
    }
}

response success example

{
    "requestId": "uuid",
    "msg": "success",
    "code": 200,
    "payload": {
        "sku": "H7143",
        "device": "52:8B:D4:AD:FC:45:5D:FE",
        "capabilities": [
            {
                "type": "devices.capabilities.online",
                "instance": "online",
                "state": {
                    "value": false
                }
            },
            {
                "type": "devices.capabilities.on_off",
                "instance": "powerSwitch",
                "state": {
                    "value": 0
                }
            },
            {
                "type": "devices.capabilities.toggle",
                "instance": "warmMistToggle",
                "state": {
                    "value": 0
                }
            },
            {
                "type": "devices.capabilities.work_mode",
                "instance": "workMode",
                "state": {
                    "value": {
                        "workMode": 3,
                        "modeValue": 9
                    }
                }
            },
            {
                "type": "devices.capabilities.range",
                "instance": "humidity",
                "state": {
                    "value": ""
                }
            },
            {
                "type": "devices.capabilities.toggle",
                "instance": "nightlightToggle",
                "state": {
                    "value": 1
                }
            },
            {
                "type": "devices.capabilities.range",
                "instance": "brightness",
                "state": {
                    "value": 5
                }
            },
            {
                "type": "devices.capabilities.color_setting",
                "instance": "colorRgb",
                "state": {
                    "value": 16777215
                }
            },
            {
                "type": "devices.capabilities.mode",
                "instance": "nightlightScene",
                "state": {
                    "value": 5
                }
            }
        ]
    }
}

example for sensor

capabilities

{
    "sku": "H5140",
    "device": "FD:C8:DC:1E:D5:51:65:24",
    "deviceName": "Smart CO2 Monitor",
    "type": "devices.types.air_quality_monitor",
    "capabilities": [
    {
        "type": "devices.capabilities.property",
        "instance": "carbonDioxideConcentration"
    },
    {
        "type": "devices.capabilities.property",
        "instance": "sensorTemperature"
    },
    {
        "type": "devices.capabilities.property",
        "instance": "sensorHumidity"
    }]
}

request

POST /router/api/v1/device/state HTTP/1.1
Host: test-openapi.api.govee.com
Content-Type: application/json
Govee-API-Key: f3c79a11-d6d6-479b-87b5-3d160320edb9
Content-Length: 138

{
  "requestId": "6efd6c77-a0ec-4a0c-8e35-e88f73ce76ea",
  "payload": {
    "sku": "H5140",
    "device": "FD:C8:DC:1E:D5:51:65:24"

  }
}

response

{
    "requestId": "6efd6c77-a0ec-4a0c-8e35-e88f73ce76ea",
    "msg": "success",
    "code": 200,
    "payload": {
        "sku": "H5140",
        "device": "FD:C8:DC:1E:D5:51:65:24",
        "capabilities": [
            {
                "type": "devices.capabilities.online",
                "instance": "online",
                "state": {
                    "value": true
                }
            },
            {
                "type": "devices.capabilities.property",
                "instance": "carbonDioxideConcentration",
                "state": {
                    "value": 1590
                }
            },
            {
                "type": "devices.capabilities.property",
                "instance": "sensorTemperature",
                "state": {
                    "value": 79.52
                }
            },
            {
                "type": "devices.capabilities.property",
                "instance": "sensorHumidity",
                "state": {
                    "value": 61.2
                }
            }
        ]
    }
}

response field

field	data type
sku	String	Product model
device	String	device id
deviceName	String	The device name in Govee Home App.
capabilities	Array	device capabilities array

Capabilities Array

field	data type
type	String	capbility type
instance	String	capability instance
state	Object	the struct definition of current state in this instance

State Define Object

enum control value

field	data type	desc
value	Object	The type of value depends on the dataType returned by Get You Device.

In capabilities, if type is 'devices.capabilities.online', it indicates whether the device is wifi online. If it is false, the status data queried is historical data and has no reference significance. If state is true, it means the device is online, and the returned value is the value of the current device status. These values correspond to the list returned by Get You Device. If the value value is empty, it means that the instance does not support query.

In capabilities, if the type is 'devices.capabilities.event', this is a property of real-time monitoring. It will only be reported when the event occurs on the device and cannot be obtained through query. If you want to obtain the status in real time, please refer to 'Subscribe Device Event' interface

Friendly Reminder
if the request response 429, means request limits happens, 10000/Account/Day