Soracom Harvest Data

Collecting Data

To collect data using Harvest, simply configure your Air for Cellular or Inventory device to send data using one of Harvest's entry points.

Data transmitted from Sigfox and LoRa devices is automatically captured when Harvest is enabled. No entry point configuration is required for Sigfox and LoRa devices.

HTTP

This entry point accepts HTTP POST requests from an Air for Cellular or Soracom Inventory device.

Entry Point

For Air for Cellular devices, your device should be configured to send data to: http://harvest.soracom.io.

For Soracom Inventory devices, your device should be configured to send data to: https://api.soracom.io/v1/devices/{DEVICE-ID}/publish?device_secret={DEVICE-KEY-SECRET}

In either case, the HTTP request should include a Content-Type header to indicate the type of data.

Harvest will return one of the following HTTP responses:

Examples

curl -X POST \
>  -H 'Content-Type: application/json' \
>  -d '{"temperature":20}' \
>  http://harvest.soracom.io

Harvest can also accept POSTs as plain text

$ curl -v -X POST http://harvest.soracom.io \
-H 'Content-Type: text/plain' \
-d 'Hello, SORACOM Harvest Data!'

By default, Harvest will automatically associate a timestamp with the received data based on the date and time the request was received. To specify a different timestamp, you can include an X-Soracom-Timestamp HTTP header, using a Unix timestamp in milliseconds:

$ curl -X POST \
>  -H 'Content-Type: application/json' \
>  -H 'X-Soracom-Timestamp: 1545652714887' \
>  -d '{"temperature":20}' \
>  http://harvest.soracom.io

To save a timestamp in Soracom Harvest Data and use them with the "Date & Time / DateTim ISO" panel within Lagoon 3, timestamps within the JSON body need to be sent to Harvest as UNIX time measuered in milliseconds. Timestamps in any other format may result in the date becoming malformed when displayed in the Lagoon 3 panel

Customers can specify a Timestamp only when sending data directly to harvest.soracom.io, not when sending data to the Unified Endpoing (unified.soracom.io or uni.soracom.io)

When using X-Soracom-Timestamp and specifying a time that is in the past and beyond the data retention period, the the data cannot be viewed with Harvest Data

TCP & UDP

This entry point accepts TCP and UDP traffic from an Air for Cellular device.

Entry Point

Your device should be configured to send data to tcp://harvest.soracom.io:8514 or udp://harvest.soracom.io:8514.

Since TCP and UDP do not have a request and response mechanism like HTTP, Harvest will return a TCP packet containing a status code to the device to indicate whether or not data was successfully sent:

Example

telnet harvest.soracom.io 8514
>Trying 100.127.127.100...
>Connected to 100.127.127.100.
>Escape character is '^]'.
>
>hello
>201
>^]
>
>telnet> quit
>Connection closed.

SMS & USSD

This entry point accepts SMS and USSD messages from an Air for Cellular device.

Entry Point

When sending a SMS message, your device should be configured to send it to 901031.

When sending a USSD message, your device should be configured to send it to *901031*{data}#.

Both SMS and USSD have character length and character encoding limitations. Please refer to the SMS & USSD documentation for more information.

Harvest will not send any response to the device upon receipt of SMS or USSD data.

Data Format

In order for Harvest to automatically generate chart data, your data must be sent to Harvest in JSON format similar to the following:

{
  "key1": 10,
  "key2": 20
}

When sending geographical location data, ensure that your JSON data includes the following keys:

{
  "lat": 36.2048,
  "lng": 138.2529,
  // other data
}

A maxiumum of 1KB (1024 bytes) may be sent to Harvest per request. Data can be shortened to a single line while keeping the same JSON structure, in order to minimize data usage.