Enterprise API

Edit

Overview

The Enterprise API is an open API service for those enterprise who has already connected to Gizwits cloud platform and want to go further to bring device data into some vertical industry in order to unlock its business insights. Using the data generated by the enterprise in the Gizwits cloud platform, it provides companies with device management, data analytics, and other functions at the enterprise level and with a holistic viewpoint, which allows you to focus on business management system itself and reduce unnecessary development costs and time.

APIs

Based on the services powered by Gizwits, Enterprise API accomplishes following functions:

• Authorization: Get a token for enterprise developers.

API List	Description
post_v1_products_product_key_access_token	Get required access permissions that the caller has on Enterprise API

• Product Management: Get product data points.

API List	Description
get_v1_products_product_key_datapoint	Get data point information for a given product

• User Management: Search for registered users and binding users etc.

API List	Description
get_v1_products_product_key_users_search	Search for registered user information
get_v1_users_search	Search for binding user information

• Device Management: Get device did, device details, device enumeration, device online and offline records, communication logs, historical data in 2 days by default and control remote devices etc.

API List	Description
get_v1_products_product_key_devices	Get device did
get_v1_products_product_key_device_detail	Get device details
get_v1_products_product_key_devices_search	Enumerate devices
get_v1_products_product_key_devices_did_data	Get KV value of a given device in 2 days by default
get_v1_products_product_key_devices_did_online	Get device online and offline records
get_v1_products_product_key_devices_did_cmd	Get device raw instructions of a given device in 2 days by default
post_v1_products_product_key_devices_did_control	Control a device remotely

• Device Grouping: Create a device group, list all devices of a device group, delete a device group, update a device group and list all MACs under a given device group etc.

API List	Description
get_v1_products_product_key_device_groups	Get the device group tree structure of a given product
post_v1_products_product_key_device_groups	Create a device group
delete_v1_products_product_key_device_groups_gid	Delete a device group
get_v1_products_product_key_device_groups_gid	List all MACs under a given device group
put_v1_products_product_key_device_groups_gid	Update a device group

• Binding Management: Bind and unbind devices.

API List	Description
post_v1_products_product_key_devices_bindings	Bind devices
delete_v1_products_product_key_devices_bindings	Unbind devices

• Device Reporting: Provides device activation reports, geographical distribution, overview, activation details, activity details, device faults, and device alarm reports.

API List	Description
get_v1_products_product_key_devices_report_activation	Get device activation statistics report
get_v1_products_product_key_devices_locations	Get device geographical distribution
get_v1_products_product_key_summary	The number of recent activations and active devices
get_v1_products_product_key_incr_devices	Custom query for activated device details
get_v1_products_product_key_active_devices	Custom query for active device details
get_v1_products_product_key_devices_report_liveness_history	Query historical reports of active devices by day, week, and month
get_v1_products_product_key_devices_report_rt	Query device status report
get_v1_products_product_key_fault_report_devices	Get faulty device report
get_v1_products_product_key_alert_report_devices	Get alarm device report
get_v1_products_product_key_fault_report_events	Get device fault report
get_v1_products_product_key_fault_alert_events	Get device alarm report

• User Reporting：Provides new user report, active enterprise user report, geographical distribution of users, and total number of users.

API List	Description
get_v1_products_product_key_users_report_new	This refers to the new users who has bound the product with its PK
get_v1_users_liveness_total	Active enterprise users
get_v1_users_location	User geographical distribution
get_v1_products_product_key_users_report_total	The total number of users

Specification

1. Request methods

The APIs defined in this document is based on the HTTP/HTTPS protocol. Please note the request methods marked in the protocol which perform different actions through GET, PUT, and DELETE.

2. Request URL

The variables included in each API URL with the ${ } need to be substituted altogether for the corresponding variables. For example, ${product_key} indicates that the product_key value needs to be assigned to the API URL, ${token value} indicates that it needs to be replaced by the token obtained through the authorization API, and ${did} indicates that it needs to be replaced with the specific did value.

3. Request parameters

The types of HTTP request parameters are generally categorized into three types, the names of which are Header, URL path and Body. Header indicates that the parameter is in the HTTP request header; the URL path indicates that the parameter is passed in the URL path; Body indicates that it is in the request body, and usually accepts data in JSON format.

4. HTTP request header

Those APIs of device management and device reporting in this document should be accessed with the token at the request header to verify whether the caller has the permission on it. The token value is obtained by the authorization API.
The request header requires the following format.

Content-Type: application/json
Authorization: token ${token value}

Note: The ${} should be excluded from the ${token value}, just add the token value next to the token. For example: Authorization: token efbekskdklllsF

5. HTTP response header

If the action is successful, the service sends back a response which looks like this:

X-RateLimit-Limit: 60     //Request limit 
X-RateLimit-Remaining: 56 //Remaining visits
X-RateLimit-Reset: 1372700873 //Request frequency reset time, TS type

6. Token lifecycle

The Token value is valid for 7 days. The expired_at field returned by the authorization API is the expiration timestamp. If the current timestamp > expired_at timestamp, you need to re-acquire the token using “Get an access token”.

7. Request quota

Enterprise API allows you to make 3600 requests in one hour by default. The request will fail if it exceeds the request limit. After one hour, the API call is resumed. For details, see the system error code 5013 in the error code table.

Online debugger

We provide Enterprise API debugging tools. The corresponding debug link is given in each API description.
The following example uses user management to illustrate the use of API debugging tools:

• Click user management to enter the API debugging page
• There is a red exclamation mark on the right side of the API. After clicking it, a dialog box pops up prompting for the required header information.
• The API needs to enter the X-Gizwits-Application-Id, get the AppID according to the previous instructions and fill it in, click “Authorize” to authorize
• The page is automatically refreshed and the exclamation mark turns blue, indicating that the required header information has been filled in (filled does not necessarily indicate that the value is correct. If the value is incorrect, the corresponding result will be returned in the response)
• Enter the parameter value in the input box (click the Example Value yellow box to the right of the parameter to enter the sample JSON quickly)
• Click the “Try” button to complete the API request
• The request completes, displaying the equivalent curl statement of local call, request URL, response body, response code, and response header

Authorization

Get an access token

Debug console

Request method and URL

POST
http://enterpriseapi.gizwits.com/v1/products/{product_key}/access_token

Request parameters

Params	Data Type	Required	Param Type	Description
product_key	string	Yes	path	Product key
enterprise_id	string	Yes	body	Enterprise ID
enterprise_secret	string	Yes	body	Enterprise secret
product_secret	string	Yes	body	Product secret

Response parameters

Params	Data Type	Description
token	string	User token
expire_at	integer	Token expiration time (timestamp)

Example response

{
  "token": "89d753a234ef42cd90f75da7489e78a4",
  "expired_at": 1517897923
}

Product Management

Get product data points

Debug console

Request method and URL

GET
http://enterpriseapi.gizwits.com/v1/products/{product_key}/datapoint

Request parameters

Params	Data Type	Required	Param Type	Description
product_key	string	Yes	path	Product key

Response parameters

Params	Data Type	Description
name	string	Product name
entities	Array	[EntitiyList]
protocolType	string	Fixed value: standard
product_key	string	Product key
packetVersion	string	Fixed value: 0x00000004
ui	inline_model_7	Mobile client UI definition
EntitiyList	——————	——————
id	integer	Fixed value: 0
name	string	Fixed value: entity0
display_name	string	Fixed value: Gizwits development kit
attrs	Array	[AttrItem]
inline_model_7	——————	——————
object	inline_model_1
sections	Array	UI section list:[SectionItem]
AttrItem	——————	——————
id	integer	Data point order
name	string	Data point name
display_name	string	Data point display name
desc	string	Fixed value: …..
type	string	Read/write type, W: Read/write, R: Read only, N: Alarm, E: Fault
data_type	string	Data type, bool: Boolean type; ‘uint8’, ‘uint16’, ‘uint32’: numeric type; enum: enumeration type; binary: extended type]
uint_spec	inline_model_4	This field is available when data_type is uint8/uint16/uint32
enum	Array	This field is available when data_type is enum
position	inline_model_5	Byte and Bit position description
inline_model_1	——————	——————
version	integer	Fixed value: 4
showEditButton	boolean	Fixed value: false
SectionItem	——————	——————
elements	Array	[ElementItem]
inline_model_4	——————	——————
min	integer	Minimum value
max	integer	Maximum value
ratio	number	Ratio k
addition	integer	Increment
inline_model_5	——————	——————
bit_offset	integer	Bit index, fixed to 0 if it’s a variable length protocol
len	integer	length
unit	string	Unit, ‘bit’, ‘byte’
byte_offset	integer	Byte index, fixed to 0 if it’s a variable length protocol
ElementItem	——————	——————
title	string	Data point display name
key	string	entity0.{Data point name}
type	string	‘QBooleanElement’, ‘QFloatElement’, ‘QRadioElement’, ‘QMultilineElement’, ‘QLabelElement’
keyboardType	string	Keyboard type, fixed value: ,”NumbersAndPunctuation”
maxLength	integer	This field is only available for type QMultilineElement, the maximum length, which is 2 times the defined length of the data point.
items	Array	This field is only available for type QRadioElement, enumeration value list
boolValue	boolean	This field is only available for type QBooleanElement, fixed value: false
bind	string	This field is only available for type QFloatElement, fixed value: floatValue:float
maximumValue	number	This field is only available for type QFloatElement, the maximum value
minimumValue	number	This field is only available for type QFloatElement, the minimum value
value	integer	This field is only available for type QFloatElement. fixed value: 0
object	inline_model_6
inline_model_6	——————	——————
action	string	Fixed value: entity0
bind	Array[string]	Fixed value: entity0.{data point name}
perm	string	Read/Write type: W: Read/Write, R: Read Only, N: Alarm, E: Fault
unit_spec	inline_model_2	This field is only available for type QFloatElement
inline_model_2	——————	——————
max	integer	The maximum value
step	integer	Step value
min	integer	The minimum value

Example response

{
  "name": "微信宠物屋",
  "entities": [
    {
      "id": 0,
      "display_name": "机智云开发套件",
      "attrs": [
        {
          "display_name": "开关",
          "name": "switch",
          "data_type": "bool",
          "position": {
            "bit_offset": 0,
            "len": 1,
            "unit": "bit",
            "byte_offset": 0
          },
          "type": "status_writable",
          "id": 0,
          "desc": "....."
        }
      ],
      "name": "entity0"
    }
  ],
  "protocolType": "standard",
  "product_key": "4244bf2d79694a259232431b6f2ef46a",
  "packetVersion": "0x00000004",
  "ui": {
    "object": {
      "version": 4,
      "showEditButton": false
    },
    "sections": [
      {
        "elements": [
          {
            "boolValue": false,
            "object": {
              "action": "entity0",
              "bind": [
                "entity0.switch"
              ],
              "perm": "W"
            },
            "type": "QBooleanElement",
            "key": "entity0.switch",
            "title": "开关"
          }
        ]
      }
    ]
  }
}

User Management

Search for registered users

This API is used to search for registered user information.

Debug console

Request method and URL

GET
http://enterpriseapi.gizwits.com/v1/users/search

Request parameters

Params	Data Type	Required	Param Type	Description
X-Gizwits-Enterprise-ID	string	Yes	header	enterprise id
X-Gizwits-Enterprise-Secret	string	No	header	enterprise secret
product_key	string	Yes	query	Product key
appid	string	No	query	Application ID
username	string	No	query	User name
phone	string	No	query	Mobile phone number
email	string	No	query	Email address
limit	integer	No	query	The number of returned records, 20 by default
skip	integer	No	query	The number of skipped records, 0 by default

Response parameters

Params	Data Type	Description
total	integer	The total number of records
limit	integer	The number of records returned
skip	integer	The number of skipped records
previous	string	Previous page request address
next	string	Next page request address
uid	string	User ID
username	string	User name
phone	string	Mobile phone number
email	string	Email address
birthday	string	Birthday date
is_anonymous	boolean	Whether it is an anonymous user
gender	string	Gender
address	string	Address
remark	string	Notes
created_at	integer	Creation time
updated_at	integer	Update time

Example response

{
  "meta": {
    "previous": null,
    "skip": 0,
    "total": 20,
    "limit": 20,
    "next":null
  },
  "objects": [
    {
      "username": null,
      "remark": null,
      "uid": "25a5324c807842348f63ade277eb413a",
      "is_anonymous": true,
      "gender": null,
      "created_at": 1513135417,
      "updated_at": 1513135417,
      "phone": null,
      "birthday": null,
      "address": null,
      "email": null
    }
  ]
}

Search for binding users

Debug console

This API is used to search for binding user information.

• Only returns the device’s owner permissions when searching by device did, true: has ownership, false: does not have ownership

Request method and URL

GET  
http://enterpriseapi.gizwits.com/v1/products/{product_key}/users/search

Request parameters

Params	Data Type	Required	Param Type	Description
product_key	string	Yes	path	Product key
gid	string	No	query	Group ID
type	string	No	query	Type
val	string	No	query	Query condition value
limit	integer	No	query	The number of returned records
skip	integer	No	query	The number of skipped records

Response parameters

Params	Data Type	Description
total	integer	The total number of records
limit	integer	The number of returned records
skip	integer	The number of skipped records
previous	string	Previous page request address
next	string	Next page request address
uid	string	User ID
username	string	User name
phone	string	Mobile phone number
email	string	Email address
birthday	string	Birthday date
address	string	Address
remark	string	Notes
created_at	integer	Creation time
is_anonymous	boolean	Whether it is an anonymous user
auth_src	object	Third-party authentication information
is_owner	boolean	Only returns the device’s ownership when searching by device did, true: has ownership, false: does not have ownership

Example response

{
  "meta": {
    "previous": null,
    "skip": 0,
    "total": 30,
    "limit": 20,
    "next": null
  },
  "objects": [
    {
      "username": null,
      "remark": null,
      "uid": "2ac80784a695a5f88f63ade277eb413a",
      "is_anonymous": true,
      "gender": null,
      "created_at": 1513135417,
      "auth_src": null,
      "phone": null,
      "birthday": null,
      "address": null,
      "email": null,
      "name": null
    }
  ]
}

Device Management

Get device did

Debug console

Request method and URL

GET
http://enterpriseapi.gizwits.com/v1/products/{product_key}/devices

Request parameters

Params	Data Type	Required	Param Type	Description
product_key	string	Yes	path	Product key
mac	string	Yes	query	MAC address

Response parameters

Params	Data Type	Description
did	string	Device ID

Example response

{
  "did": "cBYkSjoE2xspYMhaUHdk5k",
  "passcode": "123456"
}

Get device details

Debug console

Request method and URL

GET
http://enterpriseapi.gizwits.com/v1/products/{product_key}/device_detail

Request parameters

Params	Data Type	Required	Param Type	Description
product_key	string	Yes	path	Product key
mac	string	Yes	query	MAC address

Response parameters

Params	Data Type	Description
product_key	string	Product key
mac	string	MAC address
did	string	Device ID
is_online	boolean	Whether the device is online, True means online, False means offline
is_disabled	boolean	Whether the device is logged off, True means logged off, False means not logged off
type	string	Device type

Example response

{
  "did": "dE2xjocBhaUHkYkSspYM5k",
  "is_disabled": false,
  "product_key": "6f2e214bf2d79649232431b94a25f46a",
  "mac": "virtual:site",
  "is_online": false,
  "type": "normal"
}

Enumerate devices

Debug console

Request method and URL

GET  
http://enterpriseapi.gizwits.com/v1/products/{product_key}/devices/search

Request parameters

Params	Data Type	Required	Param Type	Description
product_key	string	Yes	path	Product key
gid	string	No	query	Device group ID
country	strin	g No	query	Country
region	string	No	query	Province
city	string	No	query	City
is_online	integer	No	query	Whether the device is online, 1 means online, 0 means offline
is_faulty	integer	No	query	Whether a fault exists, 1 means yes, 0 means no
is_alert	integer	No	query	Whether an alarm exists, 1 means yes, 0 means no
show_disabled	integer	No	query	1 means to display logout devices, and 0 means to filter out logout devices
liveness_start	string	No	query	Most recently active timestamp
type	string	No	query	Its value can be did, mac, uid
val	string	No	query	Query condition value
limit	integer	No	query	The number of returned records
skip	integer	No	query	The number of skipped records

Response parameters

Params	Data Type	Description
total	integer	The total number of records
limit	integer	logout
skip	integer	logout
previous	string	Previous page request address
next	string	Next page request address
did	string	Device ID
mac	string	MAC address
is_online	integer	Whether the device is online
country	string	Country
region	string	Province
city	string	City
longitude	string	Longitude
latitude	integer	Latitude
is_faulty	integer	Whether a fault happens
is_alert	integer	Whether an alarm happens
online_latest	integer	The device most recently online time
created_at	integer	Device creation time
mcu_hard_version	string	MCU hardware version
mcu_soft_version	string	MCU software version
wifi_hard_version	string	Wi-Fi hardware version
wifi_soft_version	string	Wi-Fi software version

Example response

{
  "meta": {
    "previous": null,
    "skip": 0,
    "total": 3,
    "limit": 20,
    "next": null
  },
  "objects": [
    {
      "city": "Guangzhou",
      "mcu_hard_version": null,
      "mcu_soft_version": null,
      "did": "kYkSE2xspYjocBhaUHdM5k",
      "country": "China",
      "region": "Guangdong",
      "mac": "virtual:site",
      "longitude": 113.280637,
      "wifi_hard_version": null,
      "online_latest": 1517296665,
      "wifi_soft_version": null,
      "is_online": false,
      "latitude": 23.125178,
      "is_alert": false,
      "created_at": 1505789918,
      "is_faulty": false
    }
  ]
}

Device remote control

Debug console

Raw instructions (raw):

The default format is a decimal array. The binary_coding parameter can be set as hex and base64.
If you want to send a payload of binary 011000010110001001100011, after every byte of the binary string is converted to a decimal, you will get an array: [97,98,99];
If you want to send a payload of hexadecimal 616263, after every byte of the binary string is converted to a decimal, you will get an array: [97,98,99].

{
  "raw": [97,98,99]
}

Data point (attrs):

Device products must have defined data points. If you want to set the value of the extended field binary to hexadecimal 1234567, you need to pad the extended field to the given length:
The default type of the extended field is hex16, and base64 can be used to set the binary_coding parameter as well.

{
  "attrs": {
    "binary": "1234567000"
  }
}

Request method and URL

POST
http://enterpriseapi.gizwits.com/v1/products/{product_key}/devices/{did}/control

Request parameters

Params	Data Type	Required	Param Type	Description
product_key	string	Yes	path	Product key
did	string	Yes	path	Device ID
raw	Array[integer]	Yes	body	Raw instruction method
attrs	object	Yes	body	Data point method

Response parameters

No

Get device online and offline records

Debug console

This API is used to query online and offline records for any two days in the last 7 days.

Time & Sorting:

• If start_ts and end_ts fields are not filled, it is to query the communication log records within the past two days in the default way.
• The interval between start_ts and end_ts must be within two days
• It support sorting with the sort field, it is descending order by default. Pass in asc for ascending order, desc for descending order

The offline reason of the device (reason)

• mqtt_disconnect: The device actively disconnected from mqtt
• no_heartbeat: m2m did not receive any device heartbeat during the KeepAlive period
  Tcp_closed: The device actively terminated tcp connections
• ssl_closed: The device actively terminated the ssl connection
• offline_force: The device goes online again and the original connection is terminated
• offline_reset: The device is logged out and disconnected
• offline_exception: Abnormal disconnection
• offline_sending_density_overflow: The client sent the message too often and disconnected
• offline_sending_data_size_overflow: The client sent too much traffic and disconnected

Request method and URL

GET
http://enterpriseapi.gizwits.com/v1/products/{product_key}/devices/{did}/online

Request parameters

Params	Data Type	Required	Param Type	Description
product_key	string	Yes	path	Product key
did	string	Yes	path	Device did
start_ts	integer	No	query	Start timestamp
end_ts	integer	No	query	End timestamp
sort	sort	No	query	Its value can be desc or asc
limit	integer	No	query	The number of returned records
skip	integer	No	query	The number of skipped records

Response parameters

Params	Data Type	Description
total	integer	The total number of records
limit	integer	The number of returned records
skip	integer	The number of skipped records
previous	string	Previous page request address
next	string	Next page request address
timestamp	integer	Device online/offline instruction received time
type	string	Device log types, such as: dev_online/dev_offline, etc.
payload	string	Device raw log
KeepAlive	integer	Heartbeat interval specified by the device (in seconds)
duration	integer	Online duration of the device (unit: seconds)
count	integer	The number of heartbeats sent when online
max	integer	Maximum interval
min	integer	Minimum interval
avg	integer	Average interval
last	integer	The time span between the last time the heartbeat was received and the offline time
reason	string	Offline reason

Example response

{
  "meta": {
    "previous": null,
    "skip": 0,
    "total": 5,
    "limit": 20,
    "next": null
  },
  "objects": [
    {
      "timestamp": 1517384124.229,
      "type": "dev_online",
      "payload": {
        "keep_alive": 130
      }
    },
    {
      "timestamp": 1517298056.201,
      "type": "dev_offline",
      "payload": {
        "duration": 1391,
        "heartbeat": {
          "count": 21,
          "max": 60,
          "avg": 60,
          "last": 130,
          "min": 60
        },
        "reason": "no_heartbeat"
      }
    }
  ]
}

Get device communication log

Debug console

This API is used to query device communication log for any two days in the last 7 days (raw data).

Time & Sorting:

• If start_ts and end_ts fields are not filled, it is to query the communication log records within the past two days in the default way.
• The interval between start_ts and end_ts must be within two days
• It support sorting with the sort field, it is descending order by default. Pass in asc for ascending order, desc for descending order

payload：

• payload is base64-encoded for binary.

Request method and URL

GET
http://enterpriseapi.gizwits.com/v1/products/{product_key}/devices/{did}/cmd

Request parameters

Params	Data Type	Required	Param Type	Description
product_key	string	Yes	path	Product key
did	string	Yes	path	Device did
start_ts	integer	No	query	Start timestamp
end_ts	integer	No	query	End timestamp
sort	sort	No	query	Its value can be desc or asc
limit	integer	No	query	The number of returned records
skip	integer	No	query	The number of skipped records

Response parameters

Params	Data Type	Description
total	integer	The total number of records
limit	integer	The number of returned records
skip	integer	The number of skipped records
previous	string	Previous page request address
next	string	Next page request address
timestamp	integer	Device online/offline instruction received time
type	string	Device log types, such as: dev2app/app2dev, etc.
payload	string	Device raw log

Example response

{
  "meta": {
    "previous": null,
    "skip": 0,
    "total": 6,
    "limit": 20,
    "next": null
  },
  "objects": [
    {
      "timestamp": 1517384252.294,
      "type": "app2dev",
      "payload": "0000000309000090010101000010"
    },
    {
      "timestamp": 1517384243.044,
      "type": "dev2app",
      "payload": "000000030b0000910401000010000000"
    }
  ]
}

Get device history data

Debug console

This API is used to query device communication log for any two days in the last 7 days (JSON format).

Time & Sorting:

• If start_ts and end_ts fields are not filled, it is to query the communication log records within the past two days in the default way.
• The interval between start_ts and end_ts must be within two days
• It support sorting with the sort field, it is descending order by default. Pass in asc for ascending order, desc for descending order

Request method and URL

GET
http://enterpriseapi.gizwits.com/v1/products/{product_key}/devices/{did}/data

Request parameters

Params	Data Type	Required	Param Type	Description
product_key	string	Yes	path	Product key
did	string	Yes	path	Device did
start_ts	integer	No	query	Start timestamp
end_ts	integer	No	query	End timestamp
sort	sort	No	query	Its value can be desc or asc
limit	integer	No	query	The number of returned records
skip	integer	No	query	The number of skipped records

Response parameters

Params	Data Type	Description
total	integer	The total number of records
limit	integer	The number of returned records
skip	integer	The number of skipped records
previous	string	Previous page request address
next	string	Next page request address
ts	integer	Device instruction received time
attrs	objects	Data points

Example response

{
  "meta": {
    "previous": null,
    "skip": 0,
    "total": 3,
    "limit": 20,
    "next": null
  },
  "objects": [
    {
      "ts": 1517384243,
      "attrs": {
        "alert_full": 0,
        "alert_shutdown": 0,
        "mode": "制冷",
        "fan_swing": 0,
        "switch": 1,
        "fan_speed": "低风",
        "fault_roomtemp": 0,
        "room_temp": -10,
        "set_temp": 16,
        "off_timing": 0,
        "on_timing": 0
      }
    }
  ]
}

Device grouping

Get the device group tree structure

Debug console

Request method and URL

GET
http://enterpriseapi.gizwits.com/v1/products/{product_key}/device_groups

Request parameters

Params	Data Type	Required	Param Type	Description
product_key	string	Yes	path	Product key

Response parameters

Params	Data Type	Description
gid	string	Device group ID

Example response

{
  "c8e4b5634b047dc495be4a05a39d02a3": ""
}

Create a device group

Debug console

• The parent_gid is an optional parameter. It means to create a device child group if it’s passed in.
• A product can have only one root device group.

Request method and URL

POST
http://enterpriseapi.gizwits.com/v1/products/{product_key}/device_groups

Request parameters

Params	Data Type	Required	Param Type	Description
product_key	string	Yes	path	Product key
parent_gid	string	No	body	Device child group ID

Response parameters

Params	Data Type	Description
gid	string	Device group ID

Example response

{
  "gid": "c8e4b5634b047dc495be4a05a39d02a3"
}

Delete a device group

Debug console

To delete a device group, you need to clear all devices and device child groups in the device group at first.

Request method and URL

DELETE
http://enterpriseapi.gizwits.com/v1/products/{product_key}/device_groups/{gid}

Request parameters

Params	Data Type	Required	Param Type	Description
product_key	string	Yes	path	Product key
gid	string	Yes	path	Device group ID

Response parameters

No

List all MACs in a device group

Debug console

Request method and URL

GET
http://enterpriseapi.gizwits.com/v1/products/{product_key}/device_groups/{gid}

Request parameters

Params	Data Type	Required	Param Type	Description
product_key	string	Yes	path	Product key
gid	string	Yes	path	Device group ID

Response parameters

Params	Data Type	Description
macs	Array[string]	MAC list

Example response

{
  "macs": [
    "virtual:site"
  ]
}

Update a device group

Debug console

• action: “assign” | “unassign”
• macs: MAC list, up to 1000 MACs at a time
• reassign: It’s valid when the action is “assign”. When reassign is true, the MAC will be moved to the current group if it is already under some device group; if the reassign is false, the move will fail if the MAC is already under some device group.

Request method and URL

PUT
http://enterpriseapi.gizwits.com/v1/products/{product_key}/device_groups/{gid}

Request parameters

Params	Data Type	Required	Param Type	Description
product_key	string	Yes	path	Product key
gid	string	Yes	path	Device group ID
action	string	Yes	body	Device group assignment type: assign,unassign
reassign	boolean	Yes	body
macs	Array[string]	Yes	body	MAC list

Response parameters

Params	Data Type	Description
failed	Array[string]	The MAC list of failure update
success	Array[string]	The MAC list of successful update

Example response

{
  "failed": [],
  "success": [
    "virtual:site"
  ]
}

Binding Management

Bind devices

Debug console

Request method and URL

POST
http://enterpriseapi.gizwits.com/v1/products/{product_key}/devices/bindings

Request parameters

Params	Data Type	Required	Param Type	Description
product_key	string	Yes	path	Product key
uid	string	Yes	body	User ID
appid	string	Yes	body	Application ID
dids	string	Yes	body	did list

Response parameters

Params	Data Type	Description
success	Array[string]	MAC list of successful binding
failed	Array[string]	MAC list of failure binding

Example response

{
  "failed": [],
  "success": [
    "jaUHdkYkSocBhE2xspYM5k"
  ]
}

Unbind devices

Debug console

Request method and URL

DELETE
http://enterpriseapi.gizwits.com/v1/products/{product_key}/devices/bindings

Request parameters

Params	Data Type	Required	Param Type	Description
product_key	string	Yes	path	Product key
uid	string	Yes	body	User ID
appid	string	Yes	body	Application ID
dids	string	Yes	body	did list

Response parameters

Params	Data Type	Description
success	Array[string]	MAC list of successful binding
failed	Array[string]	MAC list of failure binding

Example response

{
  "failed": [],
  "success": [
    "jaUHdkYkSocBhE2xspYM5k"
  ]
}

Device Reporting

Get device geographical distribution

Debug console

This API is used to get device geographical distribution report.

Request method and URL

GET
http://enterpriseapi.gizwits.com/v1/products/{product_key}/devices/locations

Request parameters

Params	Data Type	Required	Param Type	Description
product_key	string	Yes	path	Product key
gid	string	No	query	Device group ID
is_online	integer	No	query	Whether the device is online
is_faulty	integer	No	query	Whether the device is faulty
is_alert	integer	No	query	Whether the device raised an alarm

Response parameters

Params	Data Type	Description
gid	string	Device group ID
total	integer	The total number of devices
location	object	Device location information

Example response

{
  "gid": null,
  "total": 4,
  "location": {
    "China": {
      "count": 3,
      "Guangdong": {
        "count": 3,
        "Guangzhou": 3
      }
    }
  }
}

Device overview

This API can only be used in domestic environments

Debug console

Used to get the latest new activation and active device report

Request method and URL

GET
http://enterpriseapi.gizwits.com/v1/products/{product_key}/devices/locations

Request parameters

Params	Data Type	Required	Param Type	Description
product_key	string	Yes	path	Product key

Response parameters

Params	Data Type	Description
online	integer	The number of online devices
total	integer	The cumulative number of online devices
active	inline_model	Active devices
yesterday	integer	The number of active devices yesterday
7_day	integer	The number of active devices in the last 7 days
new	inline_model	Newly activated devices
today	integer	The number of newly activated devices today
yesterday	integer	The number of newly activated devices yesterday
7_day	integer	The number of newly activated devices in the last 7 days
30_day	integer	The number of newly activated devices in the last 30 days

Example response

{
  "active": {
    "7_day": 0,
    "yesterday": 0
  },
  "new": {
    "7_day": 0,
    "30_day": 0,
    "yesterday": 0,
    "today": 0
  },
  "total": 3,
  "online": 0
}

Device activation details

This API can only be used in domestic environments

Debug console

Used to get device activation details report.

Query by date

• The format of start,end is year-month-day. For example: 2016-08-01,
• Note: The response returned by Bluetooth devices fills in the device_sn field

Request method and URL

GET  
http://enterpriseapi.gizwits.com/v1/products/{product_key}/incr_devices

Request parameters

Params	Data Type	Required	Param Type	Description
product_key	string	Yes	path	Product key
start	string	No	query	Start date
end	string	No	query	End date
country	string	No	query	Country
region	string	No	query	Province
city	string	No	query	City

Response parameters

Params	Data Type	Description
total	integer	The total number of records
limit	integer	The number of returned records
skip	integer	The number of skipped records
previous	string	Previous page request address
next	string	Next page request address
report_date	string	Report date
product_key	string	Product key
mac	string	MAC address
device_sn	string	Serial number of the Bluetooth device
country	string	Country
region	string	Province
city	string	City
created_at	string	Device creation time

Example response

{
  "meta": {
    "previous": null,
    "skip": 0,
    "total": 4,
    "limit": 20,
    "next": null
  },
  "objects": [
    {
      "city": "Guangzhou",
      "country": "China",
      "region": "Guangdong",
      "report_date": "2017-12-07",
      "product_key": "4bd8778c5aa4602e5c9a5a208a1fdcc3",
      "mac": "virtual:site",
      "created_at": "2017-12-07 10:12:45"
    }
  ]
}

Active device details

This API can only be used in domestic environments

Debug console

Used to get active device details report

Query by date

• The format of start,end is year-month-day. For example: 2016-08-01,
• Note: The response returned by Bluetooth devices fills in the device_sn field

Request method and URL

GET  
http://enterpriseapi.gizwits.com/v1/products/{product_key}/active_devices

Request parameters

Params	Data Type	Required	Param Type	Description
product_key	string	Yes	path	Product key
start	string	No	query	Start date
end	string	No	query	End date
country	string	No	query	Country
region	string	No	query	Province
city	string	No	query	City

Response parameters

Params	Data Type	Description
total	integer	The total number of records
limit	integer	The number of returned records
skip	integer	The number of skipped records
previous	string	Previous page request address
next	string	Next page request address
report_date	string	Report date
product_key	string	Product key
mac	string	MAC address
device_sn	string	Serial number of the Bluetooth device
country	string	Country
region	string	Province
city	string	City
created_at	string	Device creation time

Example response

{
  "meta": {
    "previous": null,
    "skip": 0,
    "total": 19,
    "limit": 20,
    "next": null
  },
  "objects": [
    {
      "city": "Guangzhou",
      "country": "China",
      "region": "Guangdong",
      "report_date": "2017-12-28",
      "product_key": "ea202c9a5bd8708a145a4678c5afdcc3",
      "mac": "virtual:site",
      "created_at": "2017-12-28 18:45:33"
    }
  ]
}

Query historical reports of active devices

This API can only be used in domestic environments

Debug console

Active devices: Devices with data reported within one day

Result report time range

• The daily report can be queried up to 30 days.
• The weekly report can be queried up to 53 weeks.
• Monthly report can be queried up to 12 months.

Query by date

• When the cycle parameter is set with date, the format of start,end is year-month-day, example:2016-08-01,
• When the cycle parameter is set with week, the format of start,end is year-week, example:2016-51
• When the cycle parameter is set with month, the format of start,end is year-month, example:2016-12

Request method and URL

GET  
http://enterpriseapi.gizwits.com/v1/products/{product_key}/devices/report/liveness/history

Request parameters

Params	Data Type	Required	Param Type	Description
product_key	string	Yes	path	Product key
gid	string	No	query	Device group ID
cycle	string	No	query	The reference period, date, week, month
start	string	Yes	query	Start date
end	string	Yes	query	End date

Response parameters

Params	Data Type	Description
gid	string	Device group ID
cycle	string	The reference period, date, week, month
start	string	Start date
end	string	End date
date	string	Date
count	integer	Count number
location	object	Location information

Example response

{
  "start": "2017-12",
  "gid": null,
  "end": "2017-12",
  "data": [
    {
      "count": 2,
      "location": {
        "China": {
          "count": 1,
          "Guangdong": {
            "count": 1,
            "Guangzhou": {
              "count": 1
            }
          }
        }
      },
      "month": "2017-12"
    }
  ],
  "cycle": "month"
}

Query device status report

Debug console

This API is used to get device status report.

Request method and URL

GET  
http://enterpriseapi.gizwits.com/v1/products/{product_key}/devices/report/devices/report/rt

Request parameters

Params	Data Type	Required	Param Type	Description
product_key	string	Yes	path	Product key
gid	string	No	query	Device group ID

Response parameters

Params	Data Type	Description
gid	string	Device group ID
activated	integer	The activated devices number
faulty	integer	The faults number
alert	integer	The alarms number
location	object	The device geographical distribution

Example response

{
  "count": {
    "faulty": 0,
    "activated": 4,
    "alert": 1
  },
  "gid": null,
  "location": {
    "China": {
      "count": {
        "activated": 2,
        "alert": 1
      },
      "Guangdong": {
        "count": {
          "faulty": 1,
          "activated": 1,
          "alert": 1
        },
        "Guangzhou": {
          "count": {
            "activated": 3
          }
        }
      }
    }
  }
}

Get faulty device report

This API can only be used in domestic environments

Debug console

Get faulty device report

Request method and URL

GET  
http://enterpriseapi.gizwits.com/v1/products/{product_key}/fault/report/devices

Request parameters

Params	Data Type	Required	Param Type	Description
product_key	string	Yes	path	Product key
gid	string	No	query	Device group ID

Response parameters

Params	Data Type	Description
gid	string	Device group ID
total	integer	The total number of faulty deices
resolved	integer	The number of devices with all issues resolved
unresolved	integer	The number of devices with issues unresolved
location	object	The faulty device geographical distribution

Example response

{
  "gid": null,
  "count": {
    "total": 2,
    "resolved": 1,
    "unresolved": 1
  },
  "location": {
    "China": {
      "count": {
        "total": 2,
        "resolved": 1,
        "unresolved": 1
      },
      "Guangdong": {
        "count": {
          "total": 2,
          "resolved": 1,
          "unresolved": 1
        },
        "Guangzhou": {
          "count": {
            "total": 2,
            "resolved": 1,
            "unresolved": 1
          }
        }
      }
    }
  }
}

Get alarm device report

This API can only be used in domestic environments

Debug console

Used to get alarm device report.

Request method and URL

GET  
http://enterpriseapi.gizwits.com/v1/products/{product_key}/alert/report/devices

Request parameters

Params	Data Type	Required	Param Type	Description
product_key	string	Yes	path	Product key
gid	string	No	query	Device group ID

Response parameters

Params	Data Type	Description
gid	string	Device group ID
total	integer	The total number of alarm devices
resolved	integer	The number of devices with all alarms cleared
unresolved	integer	The number of devices with alarms not cleared
location	object	The alarm device geographical distribution

Example response

{
  "gid": null,
  "count": {
    "total": 2,
    "resolved": 1,
    "unresolved": 1
  },
  "location": {
    "China": {
      "count": {
        "total": 2,
        "resolved": 1,
        "unresolved": 1
      },
      "Guangdong": {
        "count": {
          "total": 2,
          "resolved": 1,
          "unresolved": 1
        },
        "Guangzhou": {
          "count": {
            "total": 2,
            "resolved": 1,
            "unresolved": 1
          }
        }
      }
    }
  }
}

Get device fault report

This API can only be used in domestic environments

Debug console

This API is used to get device fault report

Request method and URL

GET  
http://enterpriseapi.gizwits.com/v1/products/{product_key}/fault/report/events

Request parameters

Params	Data Type	Required	Param Type	Description
product_key	string	Yes	path	Product key
gid	string	No	query	Device group ID

Response parameters

Params	Data Type	Description
gid	string	Device group ID
detail	object	Data point statistics of faults
location	object	Geographical distribution of faults
total	integer	The total number of faulty devices
resolved	integer	The number of resolved issues
unresolved	integer	The number of unresolved issues

Example response

{
  "count": {
    "resolved": 1,
    "total": 1,
    "unresolved": 0
  },
  "gid": null,
  "detail": {
    "fault_roomtemp": {
      "resolved": 1,
      "total": 1,
      "unresolved": 0
    }
  },
  "location": {
    "China": {
      "count": {
        "resolved": 1,
        "total": 1,
        "unresolved": 0
      },
      "detail": {
        "fault_roomtemp": {
          "resolved": 1,
          "total": 1,
          "unresolved": 0
        }
      }
    }
  }
}

Get device alarm report

This API is used to get device alarm report

This API can only be used in domestic environments

Debug console

Request method and URL

GET  
http://enterpriseapi.gizwits.com/v1/products/{product_key}/alert/report/devices

Request parameters

Params	Data Type	Required	Param Type	Description
product_key	string	Yes	path	Product key
gid	string	No	query	Device group ID

Response parameters

Params	Data Type	Description
gid	string	Device group ID
detail	object	Data point statistics of alarms
location	object	Geographical distribution of alarms
total	integer	The total number of alarm devices
resolved	integer	The number of cleared alarms
unresolved	integer	The number of alarms not cleared

Example response

{
  "count": {
    "resolved": 1,
    "total": 1,
    "unresolved": 0
  },
  "gid": null,
  "detail": {
    "alert_full": {
      "resolved": 1,
      "total": 1,
      "unresolved": 0
    }
  },
  "location": {
    "China": {
      "count": {
        "resolved": 1,
        "total": 1,
        "unresolved": 0
      },
      "detail": {
        "alert_full": {
          "resolved": 1,
          "total": 1,
          "unresolved": 0
        }
      }
    }
  }
}

User Reporting

Get new users report

This API can only be used in domestic environments

Debug console

This refers to the new users who has bound the product with the PK

Query by date

• When the cycle parameter is set with date, the format of start,end is year-month-day, example:2016-08-01,
• When the cycle parameter is set with week, the format of start,end is year-week, example:2016-51
• When the cycle parameter is set with month, the format of start,end is year-month, example:2016-12

Request method and URL

GET
http://enterpriseapi.gizwits.com/v1/products/{product_key}/users/report/new

Request parameters

Params	Data Type	Required	Param Type	Description
product_key	string	Yes	path	Product key
gid	string	Yes	query	Device group ID
cycle	string	No	query	The reference period, date, week, month
start	string	Yes	query	Start date or start week or start month
end	string	Yes	query	End date or end week or end month

Response parameters

Params	Data Type	Description
did	string	Device group ID
cycle	string	The reference period, date, week, month
start	string	Start date
data	string	Date
count	string	Count number

Example response

{
  "start": "2017-12",
  "gid": null,
  "end": "2017-12",
  "data": [
    {
      "count": 3,
      "month": "2017-12"
    }
  ],
  "cycle": "month"
}

Get active enterprise users

Debug console

This API is used to get active enterprise users

Request method and URL

GET
http://enterpriseapi.gizwits.com/v1/users/liveness_total

Request parameters

Params	Data Type	Required	Param Type	Description
X-Gizwits-Enterprise-ID	string	Yes	header	enterprise id
X-Gizwits-Enterprise-Secret	string	Yes	header	enterprise secret
product_secret	string	Yes	query	Product key
appid	string	No	query	Application ID
start_date	string	Yes	query	Start date, like 2015-01-02
end_date	string	Yes	query	End date, like 2015-01-03

Response parameters

Params	Data Type	Description
date	string	Date
count	integer	Count number

Example response

{
  "data": [
    {
      "count": 2,
      "date": "2017-12-13"
    }
  ]
}

Get user geographical distribution

Debug console

This API is used to get enterprise user geographical distribution

Request method and URL

GET
http://enterpriseapi.gizwits.com/v1/users/location

Request parameters

Params	Data Type	Required	Param Type	Description
X-Gizwits-Enterprise-ID	string	Yes	header	enterprise id
X-Gizwits-Enterprise-Secret	string	Yes	header	enterprise secret
product_secret	string	Yes	query	Product key

Response parameters

Params	Data Type	Description
count	integer	Count number

Example response

{
  "China": {
    "count": 18,
    "Beijing": {
      "count": 14,
      "Beijing": {
        "count": 14
      }
    },
    "Guangdong": {
      "count": 4,
      "Guangzhou": {
        "count": 4
      }
    }
  }
}

Get the total number of users

This API is used to query the total number of users who has bound the product with the given PK in the user table

Debug console

Request method and URL

GET
http://enterpriseapi.gizwits.com/v1/products/{product_key}/users/report/total

Request parameters

Params	Data Type	Required	Param Type	Description
product_key	string	Yes	path	Product key
gid	string	No	query	Device group ID

Response parameters

Params	Data Type	Description
gid	string	Device group ID
total	integer	The total number of users

Example response

{
  "gid": null,
  "total": 31,
}

Error codes

Status Code	System Error Code	Description	How to fix
400	5001	body json invalid	Check the JSON string
400	5002	form invalid	The input is incorrect
404	5003	enterprise id not exist	Eid does not exist, check whether it has been requested or incorrect input
400	5004	enterprise secret error	Esecret check failed, check if it is correct
400	5005	product secret error	Product Secret check failed, check if it is correct
400	5006	product exist devicegroups
404	5007	association not exist	Need to open enterprise API service first
400	5008	association existed	Eid is not associated with the corresponding product key, please contact customer service
400	5009	token invalid	Please pass in the token or check the token field format
400	5010	token not match product_key
400	5011	token has expired	Please obtain the token again
400	5012	ip not in white list	Add IP to access white list of enterprise data for IP
403	5013	API call rate limit execeed quota	Wait for a while before using this API again
400	5014	Report has not been generated!
404	5015	Product key not exist!	Check whether the product key is correct
404	5016	Appid not exist!
404	5016	Appid not exist!
404	5017	Uid not exist!
403	5018	product operation not allowed
404	5019	organization does not exist
400	5020	can not delete published product!
400	5021	enterprise is exist
404	5022	enterprise does not exist
403	5023	enterprise is creating
403	5024	api deny to visit!
404	5025	product does not exist
403	5201	device group not belong to this product
404	5202	parent group not exist
400	5203	already has one root group
400	5204	group has subgroup
400	5205	group has device item
404	5206	group not exist
400	5207	product key not in pre assignment!
400	5208	create assign device in progress!
404	5301	device not exist Check the device ID
403	5302	device not belong to this product Please bind the device to the product first
400	5303	device not bound
400	5304	device is disabled	Activate the device
400	5305	device offline!	Get the device online
400	5401	attr invalid!	Check data point information
404	5402	datapoint data not found!	Define data points first and try again
400	5403	send command failed!	Please try it again
403	5404	remote control not allowed!	Remote control operation needs to be opened in the backend
404	5405	attrs not exist!
500	5406	Datapoints malformed
500	5407	generate meta failed
400	5408	raw data error!
500	5409	call innerapi failed!
404	5501	firmware does not exist
400	5502	firmware version has created
403	5503	firmware operation not allowed
500	5601	kairosdb query error!
403	5701	This eid has no permission to reset pwd.
403	5702	This eid has no permission to reset pwd for this appid.
400	5703	Cannot reset pwd for anonymous user
400	5801	the pks has not associate with enterprise!
400	5901	x-service secret key invalid!