Main Content

Bulk-Write CSV Data

Write many entries to channel in CSV format with single HTTP POST

expand all in page

Description

To conserve device power or group channel updates, you can use the bulk-update API. When using the bulk-update API, you collect data over time, and then upload the data to ThingSpeak™. To write data in JSON format, see Bulk-Write JSON Data. To write a single entry, see Write Data.

Note

If you set the React app with the Test Frequency set to On Data Insertion, your React is triggered only once per bulk-write request when the Condition Type matches the Condition, even if the Condition is matched more than once.

Request

HTTP Method

POST

URL

https://api.thingspeak.com/channels/<channel_id>/bulk_update.csv

URL Parameters

NameDescription

<channel_id>

(Required) Channel ID for the channel of interest.

URL example:https://api.thingspeak.com/channels/999990/bulk_update.csv

Content-Type

application/x-www-form-urlencoded

Body Parameters

NameDescriptionValue Type
write_api_key

(Required) Specify Write API Key for this specific channel. The Write API Key is on the API Keys tab of the channel view.

string

time_format

(Required) Specify absolute time of the event with time_format=absolute or time between measurements with time_format=relative.

string absolute or relative

updates

Bulk data to post to channel. Separate successive entries with a pipe character (|). Start each update with an absolute datetime or number of seconds. Separate successive fields with a comma

See Update Parameters.

Update Parameters

The update contains the data to post to your channel. The parameters appear sequentially in each update in the order shown in the table. Only one of the time specifications appears in each update.

NameDescriptionValue-Type
timestamp

(Required) If time_format=absolute, specify datetime in ISO 8601, EPOCH, or MYSQL formats. If time_format=relative, specify seconds elapsed since last entry. The timestamp must be unique within channel.

datetime or integer

field<X> data

(Required) Field X data, where X is the field ID

any

latitude

(Required) Latitude in degrees, specified as a value between -90 and 90.

decimal

longitude

(Required) Longitude in degrees, specified as a value between -180 and 180.

decimal

elevation

(Required) Elevation in meters

integer

status(Required) Message for status field entrystring

Body Format

Each CSV bulk write contains a Write API key and a time format specification. Each bulk write can contain multiple updates. Separate successive entries with a pipe character (|). Provide data or a blank entry for each sequential parameter up to the last parameter with valid data.

write_api_key=WRITE_API_KEY&time_format=TIME_FORMAT&updates=TIMESTAMP,FIELD1_VALUE,FIELD2_VALUE,FIELD3_VALUE,FIELD4_VALUE,FIELD5_VALUE,FIELD6_VALUE,FIELD7_VALUE,FIELD8_VALUE,LATITUDE,LONGITUDE,ELEVATION,STATUS | DATETIME_STAMP_OR_SECONDS_FROM_LAST_ENTRY,FIELD1_VALUE,FIELD2_VALUE,FIELD3_VALUE,FIELD4_VALUE,FIELD5_VALUE,FIELD6_VALUE,FIELD7_VALUE,FIELD8_VALUE,LATITUDE,LONGITUDE,ELEVATION,STATUS
Specify Absolute Time Format
write_api_key=XXXXXXXXXXXXXXXX&time_format=absolute&updates=2018-06-14T12:12:22-0500,1,,3,0.4,1.5,1.6,,1.8,40.0,5.4,0,wet|2018-01-30T10:26:23-0500,1.2,2.3,3,4,5,6,7,8,42.0,0.5,50,falling
Specify Relative Time Format
write_api_key=XXXXXXXXXXXXXXXX&time_format=relative&updates=4,1.1,2,0.3,,,6,7.7,0.8,41.2,19.5,100,ok|3,1,2,3,4,5,6,7,8,41.2,25.1,110,rising

Response

Success

HTTP Status Code

200 OK

Body

The response is a JSON object indicating success:

{
    "success": true
}

Error

For the full list, see Error Codes.

Limitations

  • The number of messages in a single bulk-update is limited to 960 messages for users of free accounts and 14,400 messages for users of paid accounts. The time interval between sequential bulk-update calls must be 15 seconds or more.

  • MQTT subscriptions do not report updates to the channel from bulk-write operations.

  • All updates must use same time format.

  • All timestamps must be unique. If you submit duplicate timestamps, all of your updates are rejected, otherwise only updates with timestamps already in channel are rejected.

Examples

expand all

You can configure POSTMAN to try RESTful API calls. To send an HTTP POST request to bulk-update a channel feed using a CSV formatted data, configure POSTMAN.

  1. Select POST from the drop-down list of HTTP verbs.

  2. Enter the URL, changing <channel_id> to your channel ID.

    https://api.thingspeak.com/channels/<channel_id>/bulk_update.csv

  3. Select x-www-form-urlencoded.

  4. Enter write_api_key in the Key section, and enter the Write API Key for your channel in the value section.

  5. Enter time_format in the Key section, and enter relative in the value section.

  6. Enter updates in the Key section and then enter 0,2,,,,,,,,,,,|2,2,,,,,,,,,,,|1,16,,,,,,,,,,,|2,2,,,,,,,,,,,|5,164,,,,,,,,,,,|1,22,,,,,,,,,,,|3,116,,,,,,,,,,,|

    in the value section. Use a comma for each blank entry.

  7. Send the request.

The response to the request is a JSON object indicating success. 

{
    "success": true
}

The six values posted in one call to the channel at 19:07:20 are shown in the plot. The last entry has the timestamp for the time when the request was submitted. Each update in the request with relative timestamps is decremented backwards in time from the last entry.

For devices with a built-in real-time clock, you can provide a relative timestamp for each entry. Specifytime_format=relative. Each entry starts with the time in seconds from the previous measurement.

POST /channels/266256/bulk_update.csv HTTP/1.1
Host: api.thingspeak.com
Content-Type: application/x-www-form-urlencoded
time_format: relative


write_api_key=JNWIVP3CD54ZGI9X&time_format=absolute&updates=2018-01-30T10%3A26%3A2-0500%2C2%2C%2C%2C%2C%2C%2C%2C%2C%2C%2C%2C%7C2018-01-30+10%3A26%3A23-0500%2C2%2C%2C%2C%2C%2C%2C%2C%2C%2C%2C%2C%7C2018-01-31+10%3A27%3A2-0500%2C16%2C%2C%2C%2C%2C%2C%2C%2C%2C%2C%2C%7C2018-01-31+11%3A26%3A32-0500%2C2%2C%2C%2C%2C%2C%2C%2C%2C%2C%2C%2C%7C2018-01-31+11%3A27%3A22-0500%2C164%2C%2C%2C%2C%2C%2C%2C%2C%2C%2C%2C

The message must be URL encoded. %2C and %7C represent URL encoding characters for "," and "|" respectively.

The response to the request is a JSON object indicating success. 

{
    "success": true
}
The six values posted in one call to the channel at 18:05:37 are shown in the plot.

See Also

Functions

Topics