Stream service

Stream service provides access to time-series data that has been accumulated in the channel. Before you can use the Stream service, you must have completed the following steps.

  1. Creating a new device that generates a stream (see: Stream service)
  2. Create a new channel that contains a stream (see: Channel service)
  3. Device and channel association (see: Device service)

API Sandbox

Retrieve stream

Retrieve time-series stream from thingscale.

Request Header:

Header: Description
X-APITOKEN API_TOKEN_HERE
X-TAGNAME (string) tagname as string
X-STARTTIME (string) time range as start // YYYY-MM-DD hh:ss or last
X-ENDTIME (string,required) time range as end // YYYY-MM-DD hh:ss or last
X-PAGELIMIT (string) rows per page // default as 1
X-PAGESORT (string) desc or asc // default as asc
X-AGGREGATE (string) Aggregate Mode option // avg,sum,min,max

(NOTE)X-PAGELIMIT effective when X-ENDTIME:last use. (NOTE)starttime and endtime are must be specified at local time. (NOTE)X-ENDTIME:last is not affected in Aggregate Mode.

Response Body:

Elements Type Descritption
channel number channel-Id
channel_name string channel description
last_update string last update time
stream:id number object_id
stream:tag string tag name
stream:value JSON payload // (NOTE)binary message is HEX encoded
stream:at string timestamp ISO8601

GET https://m.thingscale.io/v2/stream/{channel_id}

Parameters: channel_id (Integer)

Sample payload (Normal):

{
  "channel": 0,
    "channel_name": "sensor_1",
    "last_update": "2016-11-18T19:07:02+0900",
    "stream": [
                {
                    "_id": "582ed2c66807f4e702de3d87",
                    "tag" : null,
                    "value": {
                    "temp": 20,
                    "humid": 50,
                    "rssi": 80,
                    "vbat": 95
                },
                "at": "2016-11-18T19:07:02+0900"
                }
            ]
}

Sample payload (Use with X-AGGREGATE):

{
  "channel": 0,
    "channel_name": "sensor_1",
    "last_update": "2016-11-18T19:07:02+0900",
    "aggr_type": "min",
    "result": [
                {
                    "_id": null,
                    "value": 24.8 // min
                }
            ]
}

curl example1 (Retrieve stream from time:A to time:B)

curl -X GET -H "X-APITOKEN: API_TOKEN_HERE" -H "X-STARTTIME: YYYY-MM-DD HH:MM" -H "X-ENDTIME: YYYY-MM-DD HH:MM" -k https://m.thingscale.io/v2/stream/CHANNEL_ID_HERE

curl example2 (Retrieve newest stream)

curl -X GET -H "X-APITOKEN: API_TOKEN_HERE" -H "X-ENDTIME: last" -k https://m.thingscale.io/v2/stream/CHANNEL_ID_HERE

curl example3 (Retrieve last 5 rows)

curl -X GET -H "X-APITOKEN: API_TOKEN_HERE" -H "X-ENDTIME: last" -H "X-PAGELIMIT: 5" -k https://m.thingscale.io/v2/stream/CHANNEL_ID_HERE

curl example (retrieve last 5 rows , sort by descend)

curl -X GET -H "X-APITOKEN: API_TOKEN_HERE" -H "X-ENDTIME: last" -H "X-PAGELIMIT: 5" -H "X-PAGESORT: desc" -k https://m.thingscale.io/v2/stream/CHANNEL_ID_HERE

curl example(Aggregate mode)

curl -X GET -H "X-APITOKEN: API_TOKEN_HERE" -H "X-STARTTIME: YYYY-MM-DD HH:MM:SS" -H "X-ENDTIME: YYYY-MM-DD HH:MM:SS" -H  "X-AGGREGATE: max" -k http://m.thingscale.io/v2/stream/CHANNEL_ID_HERE

Response code:

HTTP status: Desc./Response body
200 OK Transaction OK.
401 Unauthorized {"error": "AUTH_REQUIRED"}
404 Not found { "error": "NO_CHANNEL" } // The specified channel does not exist.
404 Not found { "error": "NO_DATA" } // No datapoints exist in specified time range.
500 Internal Server Error { "error": "AGGR_ERROR" } // Some internal error occurred in Aggregate.
500 Internal Server Error { "error" : "NOSQL_ERROR"} // NoSQL error occured.
500 Internal Server Error { "error" : "NOSQL_TIMEOUT"} // NoSQL read timeout occured.

Write stream

Write time-series stream to thingscale.

Request Header:

Header: Description
X-DEVICETOKEN DEVICE_TOKEN_HERE

Request Body:

Elements Type Descritption
stream object
stream:serial string device_id
stream:value object JSON payload or numeric value

POST https://m.thingscale.io/v2/stream

Parameters: NONE

Sample payload:

{
    "stream" : [
                {
                    "serial" : "1085266243new22", // DEVICE_ID
                    "value" : 12
                }
                // Multiple Write
                {
                    "serial" : "1085266243new32",
                    "value" : "ID000004556AEE"
                }
                //
                ]
}

curl example

curl -X POST -H "X-DEVICETOKEN: DEVICE_TOKEN_HERE" -H "Content-Type: application/json" -k -d '{"stream":[{"serial":"1085266243new", "value" : 10}]}' https://m.thingscale.io/v2/stream

Response code:

HTTP status: Desc./Response body
200 OK Transaction OK.
201 Created. new device created.
400 Bad Request { "error": "DEVICE_ID_ZERO" } // deivce_id:0 is not allowed.(or device_id:NULL)
401 Unauthorized {"error": "AUTH_REQUIRED"}
403 Forbidden { "error": "NO_MAPPED_CH" } // Sender device's serial number is not map to channel.
403 Forbidden { "error": "DEVICE_DISABLED" } // Devices status is disabled.
500 Internal Server Error { "error" : "NOSQL_ERROR"} // NoSQL error occured.

results matching ""

    No results matching ""