Bulk-Write CSV Data

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

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

Name	Description
`<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

Name	Description	Value 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.

Name	Description	Value-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 entry	string

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

Create a POSTMAN Request with Relative Timestamps

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.

Select POST from the drop-down list of HTTP verbs.
Enter the URL, changing <channel_id> to your channel ID.
https://api.thingspeak.com/channels/<channel_id>/bulk_update.csv
Select x-www-form-urlencoded.
Enter write_api_key in the Key section, and enter the Write API Key for your channel in the value section.
Enter time_format in the Key section, and enter relative in the value section.
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.
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.

Bulk-Write CSV Values with Absolute Timestamps

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.