Machine Cloud API

Overview

Machine Cloud API allows you to retrieve various information about IoT Platform Machine Cloud service.
You will need a contract of "Machine Cloud" to use This API.
About NTT Com IoT Platform

Resource URL

If you want to use the global common domain, your request is sent to the nearest API gateway depending on the circumstances of your available points.

1. Base Path(Global Load Balance)

https://api.ntt.com/v1/machine-cloud

2.Base Path(Region)

https://{region}.api.ntt.com/v1/machine-cloud
  • region is jp|us|uk
  • e.g. https://us.api.ntt.com/v1/machine-cloud

Resource Information

Key Value
Response format JSON
Authentication(OAuth) Yes
Bandwidth control#1 Yes
  • #1 implement appropriate flow restriction in the customr connection unit.

Device Information API

GET /v1/machine-cloud/devices

Retreve a list of devices registered with Machine Cloud.

Request Parameters

Name Description Type Mandatory
page page number (1-10, default: 1) int False
pageSize number of lines in a page (1-100, default: 20) int False
sort sort parameter. "-" means descending order. String False

Example Request

GET /v1/machine-cloud/devices?sort=-sid

Response Parameters

Name Description Type
sid device ID int
id session ID int
name device name String
versionNo version number of device String
serialNo serial number of device String
modelSid model ID which is bound to the device int
positionGetClass get location from data/device information String
positionInfo location (latitude, longtitude) String
address address of the device String
timezoneCd timezone String
operationStatus operating status String
subInformation additional information String
deleteFlag shows if the device is deleted or not boolean

Example Result

{
    "data": {
        "0": {
         "address": "", 
         "deleteFlag": false, 
         "deviceId": "device1", 
         "modelSid": 2, 
         "name": "device_1", 
         "operationStatus": "1", 
         "positionGetClass": "1", 
         "positionInfo": "", 
         "serialNo": "ser1", 
         "sid": 4, 
         "subInformation": null, 
         "timezoneCd": "Asia/Tokyo", 
         "versionNo": "ver1"
        }
    }, 
    "detail": "", 
    "status": "success",
    "ver": "1.0.0"
}

Model Information API

GET /v1/machine-cloud/models

Retrieve the model information which includes communication profile information bound to devices.

Request Parameters

Name Description Type Mandatory
modelSid model ID int True

Example Request

GET /v1/machine-cloud/models?modelSid=1

Response Parameters

Name Description type
id ID String
name model name String
sid model ID int
mstCommand command object (described by JSON) -
profileName communication profile name String
sid command ID int
commandName command name String
commandCode command code String
mstDataPoint data point (described by JSON) -
sid data point ID int
communicationInvalidFlag shows if the datapoint is enable or disable int
dataEffectTime expiration period of the datpoint(sec.) int
dataPointCd datapoint code String
dataType type of data String
deleteFlag shows if the datapoint is deleted or not. boolean
maxValue maximum value String
minValue minimum value String
valueReceiveFormat receive format(for datetime type) int
saveKind shows if the data is saved or not. String

Example Result

{
    "data": {
     "0": {
         "defaultProfile": {
             "mstCommand": {
                 "0": {
                     "commandCd": 4096, 
                     "commandName": "command01", 
                     "mstDataPoint": {
                         "0": {
                             "communicationInvalidFlag": "0", 
                             "dataEffectTime": 1, 
                             "dataPointCd": "data1", 
                             "dataType": "02", 
                             "deleteFlag": false, 
                             "maxValue": null, 
                             "minValue": null, 
                             "saveKind": "1", 
                             "sid": 18, 
                             "valueReceiveFormat": null
                         }
                     }, 
                     "sid": 9
                 }
             }, 
             "profileName": "profile01"
         }, 
         "id": "sample01", 
         "name": "sample01", 
         "sid": 3
     }
 }, 
 "detail": "", 
 "status": "success", 
 "ver": "1.0.0"
}

Data Information API

GET /v1/machine-cloud/rawData

Retrieve data which has been uploaded during specified period by specific device

Request Parameters

Name Description Type Mandatory
deviceSid device ID int True
dataPointSid datapoint ID (multiple parameters are allowed. splitter is ",") int True
startDate start datetime (yyyyMMddHHmmss) String True
endDate end datetime (yyyyMMddHHmmss) String True
page page number (1-10, default: 1) int False
pageSize number of lines in a page (1-100, default: 20) int False
sort sort parameter. "-" means descending order. String False
maxPage maximum number of pages (1-10, default: 10) String False

Example Request

GET /v1/machine-cloud/rawData?deviceSid=214&dataPointSid=223,224&startDate=20160731000000&endDate=20160803000000&pageSize=5

Response Parameters

Name Description type
data data(described by JSON) -
measureDatetime measurement datetime(yyyyMMddHHmmss) String
value_XXX value of each datapoint. "XXX" means dataPointSid. String

Example Result

{
 "data": {
     "0": {
         "measureDatetime": "2016/07/31 00:01:11", 
         "value_223": 29, 
         "value_224": 39
     }, 
     "1": {
         "measureDatetime": "2016/07/31 00:02:02", 
         "value_223": 29, 
         "value_224": 40
     }, 
     "2": {
         "measureDatetime": "2016/07/31 00:03:02", 
         "value_223": 29, 
         "value_224": 38
     }, 
     "3": {
         "measureDatetime": "2016/07/31 00:04:02", 
         "value_223": 29, 
         "value_224": 38
     }, 
     "4": {
         "measureDatetime": "2016/07/31 00:05:02", 
         "value_223": 29, 
         "value_224": 38
     }
 }, 
 "detail": "", 
 "status": "success", 
 "ver": "1.0.0"
}