API Core Functions

Overview

This Open Platform API provides end-to-end services for device time-series data and data warehouse data, supporting identity authentication through a secure RSA token encryption mechanism. Core functions cover device data push, detail query, real-time and historical point data acquisition, as well as dataset import and query, providing standardized, secure, and reliable data interfaces for third-party system integration.

tip

Time-series Data: A series of data points with timestamps, used to describe the state or measured value of a device at a specific point in time. It is the most common data type in the Internet of Things field.

Data Warehouse Data: Business data or master data stored in a data warehouse, usually cleaned and aggregated, suitable for more complex analysis and reporting.

Before You Start

Permission Configuration

To ensure the following operational processes proceed normally, please confirm that you have Project Administrator permissions.

Token Encryption Transmission Guide

This guide aims to provide detailed instructions on how to securely use the RSA encryption algorithm for token encryption transmission within our open platform. By following this guide, you will be able to ensure the highest level of protection for sensitive data during transmission between client and server.
For specific operations, see below ->

Token Encryption Process

• Generate Key Pair
  Developers need to apply for a token within the platform application. The system will generate a key pair, and developers can download the token information (including Key ID, Key, and Public Key). The downloaded information will be used to encrypt the token, while the private key is used for decryption.
  
• Token Application and Download
  
  1. Enter Device Management
     Access Device Management; for operations, see Device Management
     
  2. Token Application and Download
     Add or download tokens; for operations, see Token Download
     
• API Interface Description
  
  tip

  Ciphertext refers to scrambled data processed by an encryption algorithm that cannot be directly read or understood. In contrast, Plaintext is the original, readable data before encryption.

  The system encrypts the token (Token) information obtained through security mechanisms using the RSA encryption algorithm, generating an encrypted ciphertext. This ciphertext is then embedded into the HTTP header of the API (Application Programming Interface) request as part of the authentication or authorization information, subsequently initiating the API request. This process ensures the confidentiality and security of token information during transmission, preventing the leakage of sensitive information (for encryption methods, please refer to the example code below).

Example Code

Python Example File

JAVA Example File

Golang Example File

.Net Example File

Node.js Example File

Common Request Error Codes

Code	Description
401	Access token expired, needs renewal
404	Incorrect interface address
428	User or tenant does not exist
429	User not registered
500	Internal server error
503	Service busy, please try again later
1000	Data *** already exists

Device Time-Series Data

Device Time-Series Data Push

tip

Can access time-series data reported by devices. Multiple devices can be pushed at once, but the total number of data entries in a single request must not exceed 1000.

URL：{neuron domain}/neurongateway/openapi/dataPlatform/openapi

HTTP Method: Post

Request Body Type: Array

Authentication: Request Header Field Description (for encryption method, see API Call Demo)

Field Name	Field Type	Required	Location	Description
X-Source-SecretId	string	Header	Yes	Key ID
X-Source-SecretKey	string	Header	Yes	Key Encrypted Text

Single Object in Array Description:

Field Name	Field Type	Required	Description
time	string	No	Device data collection time
equipmentName	string	Yes	Device name
functionType	string	Yes	Device point name
buildingName	string	Yes	Building name where the device is located (Must be consistent with the building name used during device registration)
devEui	string	No	IoT device unique identifier
value	double	No	Device point numeric value (Choose either value or reading)
reading	string	No	Device point string value (Choose either value or reading)
unit	string	No	Device point unit

Return Result Field Description

Field Name	Field Type	Description
code	int	Request response code, 200 indicates success
message	string	System message
isSuccess	boolean	Returns True on success, False on failure

Return Error Codes

See Common Request Error Codes

Device Details Query

tip

Can query detailed information for a single device.

URL: {neuron domain}/neurongateway/openapi/device/v1/mn/{devEui}

HTTP Method: Get

Authentication: Request Header Field Description (for encryption method, see API Call Demo)

Field Name	Field Type	Required	Location	Description
X-Source-SecretId	string	Header	Yes	Key ID
X-Source-SecretKey	string	Header	Yes	Key Encrypted Text

Request Parameters

Field Name	Field Type	Required	Description
devEui	string	Yes	IoT device unique identifier

Return Result Field Description

Field Name	Field Type	Description
code	int	Request response code, 200 indicates success
message	string	System message
isSuccess	boolean	Returns True on success, False on failure
data	object	Device details object

Device Details Data Object Field Description

Field Name	Description
name	Device name
alias	Device alias
equModel	Device thing model
points	Device point information corresponding to a single device (single object field description under device points)
devEUI	IoT device unique identifier
location	Device registration location information
isOnline	Whether the device is online (True means online, False means offline)
descriptions	Device description
isIot	Whether it is an IoT device (True for IoT device, False for non-IoT device)
buildingName	Device registration building name

Single Object Field Description in Device Details Points Array

Field Name	Description
type	Device point name
unit	Device point unit
bmsId	Non-IoT device point ID
control	Whether reverse control is supported (True for controllable, False for not controllable)

Return Error Codes

See Common Request Error Codes

Device List Query

tip

Can query all device information viewable under the current tenant.

URL: {neuron domain}/neurongateway/openapi/device/v1/mn/page

HTTP Method: Get

Authentication: Request Header Field Description (for encryption method, see API Call Demo)

Field Name	Field Type	Required	Location	Description
X-Source-SecretId	string	Header	Yes	Key ID
X-Source-SecretKey	string	Header	Yes	Key Encrypted Text

Request Parameters

Field Name	Field Type	Required	Description
current	int	Yes	Current page
size	int	Yes	Number of items per page
name	string	No	Device name (fuzzy match)
devEui	string	No	IoT device unique identifier (exact match)
buildingName	string	No	Building name filled during device registration (exact match)
equModel	string	No	Device thing model name (exact match)

Return Result Field Description

Field Name	Field Type	Description
code	int	Request response code, 200 indicates success
message	string	System message
isSuccess	boolean	Returns True on success, False on failure
data	object	Device list object (total: total count, size: items per page, current: current page, records: device data)

Single Object Field Description under Device Data Records

Field Name	Description
name	Device name
alias	Device alias
equModel	Device thing model
points	Device point information corresponding to a single device (single object field description under device points)
devEUI	IoT device unique identifier
location	Device registration location information
isOnline	Whether the device is online (True means online, False means offline)
descriptions	Device description
isIot	Whether it is an IoT device (True for IoT device, False for non-IoT device)
buildingName	Device registration building name

Single Object Field Description under Device Points

Field Name	Description
type	Device point name
unit	Device point unit
bmsId	Non-IoT device point ID
control	Whether reverse control is supported (True for controllable, False for not controllable)

Return Error Codes

See Request Error Codes

Device Point Latest Value Query

tip

Can query the latest values of all device points viewable under the current tenant.

URL: {neuron domain}/neurongateway/openapi/device/v1/realtime/{devEui}/values

HTTP Method: Get

Authentication: Request Header Field Description (for encryption method, see API Call Demo)

Field Name	Field Type	Required	Location	Description
X-Source-SecretId	string	Header	Yes	Key ID
X-Source-SecretKey	string	Header	Yes	Key Encrypted Text

Request Parameters

Field Name	Field Type	Required	Description
devEui	string	No	IoT device unique identifier (exact match)

Return Result Field Description

Field Name	Field Type	Description
code	int	Request response code, 200 indicates success
message	string	System message
isSuccess	boolean	Returns True on success, False on failure
data	array	Device point latest values

Single Object Field Description in Device Data Array

Field Name	Description
eqName	Device name
alias	Device alias
equModel	Device thing model
devEUI	IoT device unique identifier
state	Device Extended Status Codes
isOnline	Whether the device is online (True means online, False means offline)
descriptions	Device description
pid	Device location information (project)
building	Device registration building name
floor	Device registration floor name
room	Device registration room name
editVos	EDevice points List

Return Error Codes

See Request Error Codes

Device Point Historical Value Query

tip

Can query data values for a single or all points under a specific device for a certain period (Time range can only query data within one week).

URL: {neuron domain}/neurongateway/openapi/device/v1/realtime/history

HTTP Method: Post

Authentication: Request Header Field Description (for encryption method, see API Call Demo)

Field Name	Field Type	Required	Location	Description
X-Source-SecretId	string	Header	Yes	Key ID
X-Source-SecretKey	string	Header	Yes	Key Encrypted Text

Request Parameters

Field Name	Field Type	Required	Description
equipmentName	string	Yes	Device name (exact match)
functionType	string	No	Device point name
startTime	datatime	No	Start time
endTime	datatime	No	End time
field	string	Yes	Device point value type (VALUE for numeric, READING for string)
equModel	string	No	Device thing model name (exact match)

Return Result Field Description

Field Name	Field Type	Description
code	int	Request response code, 200 indicates success
message	string	System message
isSuccess	boolean	Returns True on success, False on failure
data	array	Device point value object

Single Field Description in Device Data Array

Field Name	Description
time	Data collection time
equipmentName	Device name
buildingName	Device registration building information
functionType	Single device point name
devEUI	IoT device unique identifier
value	Device numeric value
reading	Device string value
unit	Device point unit

Return Error Codes

See Request Error Codes

Data Warehouse Data

Data Push

tip

Can access dataset data (pushed fields and data types must correspond to the dataset configuration). Multiple entries can be pushed at once (Total data entries in a single request must not exceed 1000).

URL: {neuron domain}/neurongateway/openapi/dataset/v1/{templateCode}

HTTP Method: Post

Authentication: Request Header Field Description (for encryption method, see API Call Demo)

Field Name	Field Type	Required	Location	Description
X-Source-SecretId	string	Header	Yes	Key ID
X-Source-SecretKey	string	Header	Yes	Key Encrypted Text
X-Param-ProjectId	string	Header	Yes	Platform Project ID

Request Body Type: Array

Request Parameters

Field Name	Field Type	Required	Description
datasetName	string	Yes	Dataset ID

Return Result Field Description

Field Name	Field Type	Description
code	int	Request response code, 200 indicates success
message	string	System message
isSuccess	boolean	Returns True on success, False on failure

Return Error Codes

See Request Error Codes

Data Query

tip

Can query data values for a single or all points under a specific device for a certain period (Time range can only query data within one week).

URL: {neuron domain}/neurongateway/openapi/dataset/v1/{templateCode}

HTTP Method: Get

Authentication: Request Header Field Description (for encryption method, see API Call Demo)

Field Name	Field Type	Required	Location	Description
X-Source-SecretId	string	Header	Yes	Key ID
X-Source-SecretKey	string	Header	Yes	Key Encrypted Text
X-Param-ProjectId	string	Header	Yes	Platform Project ID

Request Parameters

Field Name	Field Type	Required	Description
equipmentName	string	Yes	Device name (exact match)
functionType	string	No	Device point name
startTime	datatime	No	Start time
endTime	datatime	No	End time
field	string	Yes	Device point value type (VALUE for numeric, READING for string)
equModel	string	No	Device thing model name (exact match)

Return Result Field Description

Field Name	Field Type	Description
code	int	Request response code, 200 indicates success
message	string	System message
isSuccess	boolean	Returns True on success, False on failure
data	array	Device point value object

Single Field Description in Device Data Array

Field Name	Description
time	Data collection time
equipmentName	Device name
buildingName	Device registration building information
functionType	Single device point name
devEUI	IoT device unique identifier
value	Device numeric value
reading	Device string value
unit	Device point unit

Return Error Codes

See Request Error Codes