v1/streams

Use the v1/streams API to manage data streams and data points. You can also use the streams web service to upload a batch of data points to streams using an XML or CVS file. See Direct device uploads.

URI

http://<hostname>/ws/v1/streams

Formats

Method	Format	Description	Parameters
GET	/ws/v1/streams	Get a summary of the streams APIs.	None
GET	/ws/v1/streams/bulk/history	Get historical data in CSV format.	order start_time end_time timeline fields
GET, POST	/ws/v1/streams/inventory	List, create, or modify data streams.	order cursor size category
GET	/ws/v1/streams/bulk	List, create, or modify data streams.	order cursor size category fields
GET	/ws/v1/streams/inventory/{stream_id}	Get a specific data stream.	order cursor size start_time end_time timezone interval method
PUT, DELETE	/ws/v1/streams/inventory/{stream_id}	Create, modify, or delete a specific data stream.
GET	/ws/v1/streams/inventory?category=carrier	Get carrier usage data for devices.
POST	/ws/v1/streams/history	Add one or more data points to a data stream
GET	/ws/v1/streams/history/{stream_id}	Get the history for a data stream.	order cursor size start_time end_time timeline
DELETE	/ws/v1/streams/history/{stream_id}	Delete the history for a data stream.	start_time end_time timeline
GET	/ws/v1/streams/rollups/{stream_id}	Get roll-up information for a data stream.
GET	/ws/v1/streams/history/{device_id}/carrier/{sim_id}/usage/{usage_id}	Get carrier usage data for a device.
GET	/ws/v1/streams/inventory?category=data	Get data streams reported by devices.
GET	/ws/v1/streams/inventory?category=metrics	Get health metrics streams reported by devices.
GET	/ws/v1/streams/inventory?category=management	Get management streams recorded for devices.

Stream fields

id

Steam identifier.

description

Stream description.

type

Data type of the stream:

integer
long
float
double
string
binary

value

Current value of the data stream.

timestamp

Date and time the current value was set.

server_timestamp

Date and time the current value was received.

stream_units

Units for the data.

forwards

List of additional streams to forward data to when received.

History fields

id

Identifier of the data point in the stream history.

stream_id

Stream identifier of the history data.

Roll-up fields

stream_id

Stream identifier for the roll-up data.

Parameters

Name	Type	Description
category	string	Return streams for the specified category: data, metrics, management, or carrier. If you do not use the category parameter, streams for all categories are returned.
cursor	string	Cursor to get the next page of devices. Omit on initial call.
end_time	timestamp	End time (exclusive) in ISO 8601 or epoch (long).
fields	string	Comma-separated list of fields to return for bulk API
interval	string	Rollup interval: half, hour, day, week, or month. The default is hour.
method	string	Rollup method: sum, average, min, max, count, standarddev. The default is average.
order	string	Return streams ordered by ID (asc \| desc). The default is ascending (asc).
size	integer	Number of items to return. The maximum and default is 1000.
start_time	timestamp	Start time (inclusive) in ISO 8601 or epoch (long).
timeline	string	Timestamps to use in the request: client or server. The default is client.
timezone	string	Timezone in which to calculate rollups. Applies only to rollups with intervals of day or longer.

Direct Device Uploads

Devices can upload directly to data streams over any of the existing transports (TCP, UDP, SMS, and Satellite). The path specified in the data service message begins with DataPoint and the rest of the message is mapped to a data stream appended to the device ID.

For example, if the device sends a data point file specifying the filename DataPoint/temp1, the data point is added to the data stream /temp1. The file must follow one of the expected formats and must specify the format via the file extension. The following types are supported for a given extension:

Format	Extension	Description
XML	.xml	XML representation same as the /ws/DataPoint interface.
CSV	.csv	Comma separated list. One data point per line with details separated by commas.
Binary	.bin	Whatever the content of the uploaded data is directly inserted to a single data point.

To maximize the speed and throughput of Remote Manager, limitations have been imposed on device uploads.

Maximum number of data points allowed per request: 250
Maximum size of Send Data requests: 2MB
Maximum size of replies to Device Requests: 2MB
Maximum number of binary data points allowed: 64KB

When devices push data points up to Remote Manager, the description included refers to the data point, not the data stream. To view the description, you must retrieve data point via web services.

XML

XML format uses the same format used in /ws/DataPoint PUT. The stream id is ignored since it is provided by the path. Also, any streams listed in the forwardTo field will be normalized to the device’s stream. This is done to prevent one device from uploading data into another device’s stream.

<DataPoint>
    <data>42</data>
    <!-- Everything below this is optional -->
    <description>Temperature at device 1</description>
    <location>0.0, 0.0, 0.0</location> 
    <quality>99</quality>
    <dataType>float</dataType>
    <units>Kelvin</units>
</DataPoint>

For multiple data points in one message:

<list>
  <DataPoint>
    <data>42</data>
    <timestamp>1234566</timestamp>
  </DataPoint>
  <DataPoint>
    <data>43</data>
  </DataPoint>
</list>

CSV

An optional upload format is to specify the data in UTF-8 encoded comma separated values. Each line ('\n' terminated) specifies a data point. The default order is:

DATA, TIMESTAMP, QUALITY, DESCRIPTION, LOCATION, DATATYPE, UNITS, FORWARDTO

Meaning the following file:

data, 1,99,"my description",,INTEGER,kelvins,"stream1,stream2"
data2,2,50,"my description"
data3,3,25,"my description"

Would create 3 data points, set the stream’s units/type to kelvins/Integers, and have the data points with the data “data”, “data2”, and “data3”, using the epoch timestamps of 1, 2, and 3.

Note that location was omitted in the above example. You can omit values by leaving them empty or stopping before the end. For example:

**Empty values:**data,1,,,99

**Ending early:**data,1

Order can be overridden. You can define a header on the first line by starting it with a ‘#’ character, for example:

#TIMESTAMP,DATA
1, data
2, data2
3, data3

Will create 3 data points 1ms apart starting at epoch (1970).

Multiple datapoints for multiple streams from a device can be inserted in one message using the STREAMID value. When the STREAMID value is specified, the file name is no longer used for the stream name.

For example:

#STREAMID,DATA,TIMESTAMP
sensor1/port1,97,1
sensor1/port2,98,1
sensor2/port1,42,1
sensor2/port2,0,2

Will create 4 data points, one in each of 4 separate streams for the device. The first 3 data points are at 1ms after the epoch (1970) and the final data point is 1ms later.

The XML version is as follows:

<list>
<DataPoint><streamId>sensor1/port1</streamId><data>97</data><timestamp>1</timestamp></DataPoint>
<DataPoint><streamId>sensor1/port2</streamId><data>98</data><timestamp>1</timestamp></DataPoint>
<DataPoint><streamId>sensor2/port1</streamId><data>42</data><timestamp>1</timestamp></DataPoint>
<DataPoint><streamId>sensor2/port2</streamId><data>0</data><timestamp>2</timestamp></DataPoint>
</list>

Binary Concise Alternative Format

The disadvantage to using the XML format is that it is very verbose. This binary alternative format can be used to be more concise. You can specify a simple value instead of XML or CSV data. When the value is pushed to /DataPoint, it is stored in complete as-is in time-series data (in the exact binary format as provided). For details on endianness, bit lengths, and so on for supported data types see the dataType in the Data Streams section. However, data types are not required. Data can be 1 byte status indicators or 10k images but Remote Manager will not be able to provide rollups on things which do not use the specified formats.

For instance, the following data service message:

path:	/DataPoint/temp1.bin
content:	42

Will result in a new data point with a value of “42” (in binary).

Note: The binary concise mechanism has the following limitations:

Only single values can be uploaded per data service message
Data must be smaller than 64k

Deciding which format to use when inserting data

Whitespace characters for the data value are preserved in all formats. Use quotes around the string for CSV format to preserve break lines. For binary data, we recommend you to use binary concise format. Binary concise format however can’t be used to create multiple data points in a single request. To create multiple binary data points in a single request, we recommend you to use a base64 encoded string.

List All Streams

Use the following API to list all streams for the current user.

Request

GET /ws/v1/streams/inventory

Response

{
    "count": 1000,
    "size": 1000,
    "cursor": "380a2605-392b-d5aa-392b-d5a9ad4571a0",
    "next_uri": "/ws/v1/streams/inventory?size=3&cursor=380a2605-392b-d5aa-392b-d5a9ad4571a0",
    "list": [
        {
            "history_uri": "/ws/v1/streams/history/F9F967B4-33804DCE-2BDC4702-45053B1C/humidity",
            "id": "F9F967B4-33804DCE-2BDC4702-45053B1C/humidity",
            "server_timestamp": "2014-02-23T19:12:59.847Z",
            "timestamp": "2014-02-23T19:12:56.510Z",
            "type": "LONG",
            "units": "%",
            "value": "44"
        },
        {
            "description": "freezer",
            "history_uri": "/ws/v1/streams/history/F9F967B4-33804DCE-2BDC4702-45053B1C/temperature",
            "id": "F9F967B4-33804DCE-2BDC4702-45053B1C/temperature",
            "server_timestamp": "2014-02-23T19:12:59.848Z",
            "timestamp": "2014-02-23T19:12:57.283Z",
            "type": "LONG",
            "units": "F",
            "value": "71"
        },
        ...
    ],
}

Get a Stream

Use the following request to get a stream.

Request

GET /ws/v1/streams/inventory/F9F967B4-33804DCE-2BDC4702-45053B1C/temperature

Response

{
    "customer_id": 57639,
    "history_uri": "/ws/v1/streams/history/F9F967B4-33804DCE-2BDC4702-45053B1C/temperature",
    "id": "F9F967B4-33804DCE-2BDC4702-45053B1C/temperature",
    "last_update": "2022-02-01T22:04:13.916Z",
    "rollup_ttl": 2678400,
    "server_timestamp": "2022-02-01T22:04:13.802Z",
    "timestamp": "2022-02-01T22:04:13.802Z",
    "ttl": 2678400,
    "type": "LONG",
    "value": "71"
}

Create a Stream

Use the following API to create (or update) one or more streams. The request payload can include a single stream or multiple streams. Multiple streams must be wrapped in an array for JSON and a element for XML. The response always returns the streams as a list.

Request

`POST /ws/v1/streams/inventory

Payload

{
    "description": "test stream",
    "id": "MyNewStream",
    "type": "LONG"
}

Response

{
    "count": 1,
    "list": [
        {
            "description": "test stream",
            "id": "MyNewStream",
            "type": "LONG"
        }
    ]
}

Create Multiple Streams

The following example shows how to create multiple streams with one stream request.

Request

POST /ws/v1/streams/inventory

Payload

[
    {
        "description": "test stream",
        "id": "MyNewStream",
        "type": "LONG"
    },
    {
        "description": "another test stream",
        "id": "MyOtherStream",
        "type": "STRING"
    }
]

Response

{
    "count": 2,
    "list": [
        {
            "description": "test stream",
            "id": "MyNewStream",
            "type": "LONG"
        },
        {
            "description": "another test stream",
            "id": "MyOtherStream",
            "type": "STRING"
        }
    ]
}

Add Multiple Datapoints to a Stream

The following example adds multiple data points to the “myStream” data stream.

Request

POST /ws/v1/streams/history

Payload

[
 {
   "stream_id": "myStream",
   "stream_type": "DOUBLE",
   "timestamp": "2014-02-23T19:37:04.517Z",
   "value": "41"
 },
 {
   "stream_id": "myStream",
   "stream_type": "DOUBLE",
   "timestamp": "2014-02-23T19:38:01.372Z",
   "value": "42"
 },
 {
   "stream_id": "myStream",
   "stream_type": "DOUBLE",
   "timestamp": "2014-02-23T19:39:02.785Z",
   "value": "43"
 }
]

Edit a Stream

Use the following API request to update (or create) a single stream.

Request

PUT /ws/v1/streams/inventory/F9F967B4-33804DCE-2BDC4702-45053B1C/temperature

Payload

{
    "units": "Celsius"
}

Response

{
    "description": "freezer",
    "history_uri": "/ws/v1/streams/history/F9F967B4-33804DCE-2BDC4702-45053B1C/temperature",
    "id": "F9F967B4-33804DCE-2BDC4702-45053B1C/temperature",
    "server_timestamp": "2014-02-23T19:12:59.848Z",
    "timestamp": "2014-02-23T19:12:57.283Z",
    "type": "LONG",
    "units": "Celsius",
    "value": "71"
}

Delete a Stream

Use the following API request to get history for data points in a stream:

DELETE /ws/v1/streams/inventory/F9F967B4-33804DCE-2BDC4702-45053B1C/temperature

A DELETE request does not return a response unless there is an error.

Get Data History for a Stream

Use the following API request to get history for data points in a stream:

Request

GET /ws/v1/streams/history/F9F967B4-33804DCE-2BDC4702-45053B1C/temperature

Response

{
    "count": 1000,
    "size": 1000,
    "cursor": "4fec418e-9cba-11e3-9a38-7cc3a1879642",
    "next_uri": "/ws/v1/streams/history/F9F967B4-33804DCE-2BDC4702-45053B1C/temperature?cursor=4fec418e-9cba-11e3-9a38-7cc3a1879642",
    "list": [
        {
            "id": "1e1b67a5-9cb6-11e3-9a38-7cc3a1879642",
            "quality": 0,
            "server_timestamp": "2014-05-08T20:05:23.358Z",
            "stream_id": "F9F967B4-33804DCE-2BDC4702-45053B1C/temperature",
            "timestamp": "2014-02-23T18:12:55.434Z",
            "value": "68"
        },
        {
            "id": "4fec418e-9cba-11e3-9a38-7cc3a1879642",
            "quality": 0,
            "server_timestamp": "2014-05-08T20:06:09.710Z",
            "stream_id": "F9F967B4-33804DCE-2BDC4702-45053B1C/temperature",
            "timestamp": "2014-02-23T18:42:56.998Z",
            "value": "70"
        }
        ...
    ]
}

Delete Stream History

Use the following API request to delete datapoints from a steam. You can delete datapoints within a time range. If no time range is specified, all datapoints are deleted.

DELETE /ws/v1/streams/history/F9F967B4-33804DCE-2BDC4702-45053B1C/temperature?start_time=2014-02-23T00:00:00.000Z&end_time=2014-02-24T00:00:00.000Z

Alternatively, you can use relative times for the start and end times. The following delete operation deletes all datapoints between 1 day and 1 second ago.

DELETE /ws/v1/streams/history/F9F967B4-33804DCE-2BDC4702-45053B1C/temperature?start_time=-1d&end_time=-1s

Get Rollup Data for a Stream

Use the following API request to get rollups of stream history. Rollups are defined by a method (average, min, max, and so on) and an interval (hourly, daily, and so on).

This request returns the average for each hour during the last day.

Request

GET /ws/v1/streams/rollups/F9F967B4-33804DCE-2BDC4702-45053B1C/temperature?method=average&interval=hour&start_time=-1d

Alternatively use a timestamp for start_time:

GET /ws/v1/streams/rollups/F9F967B4-33804DCE-2BDC4702-45053B1C/temperature?method=average&interval=hour&start_time=2014-02-23T00:00:00.000Z

Response

{
    "count": 2,
    "size": 1000,
    "start_time": "2014-02-23T00:00:00.000Z"
    "list": [
        {
            "stream_id": "F9F967B4-33804DCE-2BDC4702-45053B1C/temperature",
            "timestamp": "2014-02-23T18:00:00.000Z",
            "value": 69.0
        },
        {
            "stream_id": "F9F967B4-33804DCE-2BDC4702-45053B1C/temperature",
            "timestamp": "2014-02-23T19:00:00.000Z",
            "value": 71.0
        }
    ],
}

v1/streams

URI

Formats

Stream fields

id

description

type

value

timestamp

server_timestamp

stream_units

forwards

History fields

id

stream_id

Roll-up fields

stream_id

Parameters

Direct Device Uploads

Data limits related to direct device uploads

XML

CSV

Binary Concise Alternative Format

Deciding which format to use when inserting data

List All Streams

Request

Response

Get a Stream

Request

Response

Create a Stream

Request

Payload

Response

Create Multiple Streams

Request

Payload

Response

Add Multiple Datapoints to a Stream

Request

Payload

Edit a Stream

Request

Payload

Response

Delete a Stream

Get Data History for a Stream

Request

Response

Delete Stream History

Get Rollup Data for a Stream

Request

Response