Key｜數據存取

API Domain

https://ioeapi.nextdrive.io

Data Point Access

① Data Retrieval

Summary

① Data Retrieval

Path

GET /v2/device-data/query

Description

Through this API, you can retrieve device data by submitting REQUEST BODY with designated deviceUuid, scopes, and time range.

Request Header

X-ND-TOKEN

API Key created by IoE Suite Developer

content-type

application/json

Request Body

Example Value
JSON
{
  "deviceUuid": "498da641-cd99-4780-9f9f-cebaadcf922a",
  "scopes": [
    "normalUsage"
  ],
  "startTime": 1606694360000,
  "endTime": 1606694420000,
}

Schema
JSON
{
  "deviceUuid": string,
  "scopes": array of string,
  "startTime": Unix timestamp,
  "endTime": Unix timestamp,
  "next": string
}


200

Response

Status Code

200

Description

Successful request

Content Type

application/json

Example Value
JSON
{
    "pid": "JAQA0000000001",
    "deviceUuid": "498da641-cd99-4780-9f9f-cebaadcf922a",
    "model": "SmartMeter",
    "data": {
        "normalUsage": [
            { generatedTime": 1606694400000, "value": "1000" }
        ],
        "instanceElectricity": [
            { generatedTime": 1606694370000, "value": "546" },
            { generatedTime": 1606694400000, "value": "557" }
        ]
    },
    "next": null
}

Schema
JSON
{
  "pid": string,
  "deviceUuid": string,
  "model": string,
  "data": {
    [any-key]:[{
      "generatedTime": number,
      "value": string
    }]
  },
  "next": string
}
400

Response

Status Code

400

Description

Bad Request

Content Type

application/json

Example Value
JSON
{
  status: integer,
  title: string,
  message: string,
  path: string,
  timestamp: string
}

Schema

  • startTime should be 13 digits.

  • endTime should be 13 digits.

  • startTime cannot be a future time.

  • startTime cannot be later than endTime.
401

Response

Status Code

401

Description

Unauthorized

Content Type

application/json

Example Value
JSON
{
  status: integer,
  title: string,
  message: string,
  path: string,
  timestamp: string
}

Schema

API key is invalid
403

Response

Status Code

403

Description

Forbidden

Content Type

application/json

Example Value
JSON
{
  status: integer,
  title: string,
  message: string,
  requestId: string,
  path: string,
  timestamp: string
}

Schema

  • Device uuid (${deviceUuid}) user not subscribe related service

  • Device data scope is forbidden in this service

  • Exceeds the legal query time range (30 days)

  • StartTime cannot be earlier than 90 days ago

  • EndTime cannot be earlier than 90 days ago
404

Response

Status Code

404

Description

Not found

Content Type

application/json

Example Value
JSON
{
  status: integer,
  title: string,
  message: string,
  requestId: string,
  path: string,
  timestamp: string
}

Schema

  • Device scope (${scope}) not found

  • Device uuid (${deviceUuid}) not found
500

Response

Status Code

500

Description

System error

Content Type

application/json

Example Value

 
{
  status: integer,
  message: string,
  requestId: string,
  path: string,
  timestamp: string
}

Schema

Internal Server Error
② Device Data Acquire

Summary

② Device Data Acquire

Path

GET /v1/devices/{deviceUuid}/acquire

Description

Through this API, you can acquire devices data through the gateway.
Due to asynchronous communication, you can get data by event subscription.

After config, IoE platform pushes data to your endpoint when data is submitted by a gateway to.
For details, please refer to "WS format｜Required Data " and "ED format｜Required Data".

If you request to acquire device data by this API, a sessionId will be sent to identify the data.

Request Header

X-ND-TOKEN

API Key created by IoE Suite Developer

content-type

application/json

Request Params

Example Value
JSON
deviceUuid: "NDTEST1234567"

Schema
JSON
deviceUuid: string(NextDrive defined deviceUuid)

Request Body

Example Value
JSON
{
  "scopes": [
    "normalUsage",
    "reverseUsage"
  ]
}

Schema
JSON
{
  scopes*: [string]
}

Note

This API only works when the gateway and the device are both online.


200

Response

Status Code

200

Description

Successful request

Content Type

application/json

Example Value
JSON
{
  "requestId": "0f5b78d1-5296-493c-8700-ad9ee353d9d7"
}

Schema
JSON
{
  "requestId": string
}
401

Response

Status Code

401

Description

Unauthorized

Content Type

application/json

Example Value
JSON
{
  status: integer,
  title: string,
  message: string,
  path: string,
  timestamp: string
}

Schema

API key is invalid
403

Response

Status Code

403

Description

Forbidden

Content Type

application/json

Example Value
JSON
{
  status: integer,
  title: string,
  message: string,
  requestId: string,
  path: string,
  timestamp: string
}

Schema

  • Device uuid (${deviceUuid}) user not subscribe related service

  • Device data scope is forbidden in this service

  • Number of scope over limit
404

Response

Status Code

404

Description

Not found

Content Type

application/json

Example Value
JSON
{
  status: integer,
  title: string,
  message: string,
  requestId: string,
  path: string,
  timestamp: string
}

Schema

  • Device scope (${scope}) not found

  • Gateway associated with device (${deviceUuid}) is offline

  • Device (${deviceUuid}) is offline
500

Response

Status Code

500

Description

System error

Content Type

application/json

Example Value

 
{
  status: integer,
  message: string,
  requestId: string,
  path: string,
  timestamp: string
}

Schema

Internal Server Error