Bulk-Write JSON Data

Write many entries to a channel in JSON format with a 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 CSV format, see Bulk-Write CSV 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.json

URL Parameters

Name	Description
<channel_id>	(Required) Channel ID for the channel of interest.

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

Body Parameters and Object Members

The body of the bulk JSON write operation is a JSON object with the members and arrays listed in these tables.

Name	Description	Value Type
write_api_key	(Required for private channels) Specify the Write API Key for this specific channel. You can find the Write API Key on the API Keys tab of the channel view.	string
updates	(Required) Specify the array of updates to your channel.	array of JSON objects with the members shown in Updates

Updates

An update is a JSON array of JSON objects, that each have the following key-value pairs.

Name	Description	Value Type
created_at	(Required unless delta_t included) Absolute time of the event in ISO 8601, EPOCH, or MYSQL format. The timestamp must be unique within channel.	string
delta_t	(Required unless created_at included) Specify the seconds elapsed since the last entry with delta_t. Values for delta_t cannot be zero, except for the first value in the array.	string
field<X>	(Optional) Field X data, where X is the field ID	any
latitude	(Optional) Latitude in degrees, specified as a value between -90 and 90.	number
longitude	(Optional) Longitude in degrees, specified as a value between -180 and 180.	number
elevation	(Optional) Elevation in meters	string
status	(Optional) Message for status field entry	<string>

Content-Type

application/json

Body Format

{
	"write_api_key": "WRITE_API_KEY",
	"updates": [{
			"created_at": "DATETIME_STAMP",
			"field1": FIELD1_VALUE,
			"field2": FIELD2_VALUE,
			"field3": FIELD3_VALUE,
			"field4": FIELD4_VALUE,
			"field5": FIELD5_VALUE,
			"field6": FIELD6_VALUE,
			"field7": FIELD7_VALUE,
			"field8": FIELD8_VALUE,
			"Latitude": LATITUDE_VALUE,
			"Longitude": LONGITUDE_VALUE,
			"Elevation": ELEVATION_VALUE,
			"Status": "STATUS_STRING"
		},
		{
			"created_at": "DATETIME_STAMP",
			"field1": "FIELD1_VALUE",
			Etc...
		}
	]
}

Specify Time Format created_at

{
	"write_api_key": "WRITE_API_KEY",
	"updates": [{
			"created_at": "2018-01-30 10:26:2 -0500",
			"field1": "1.0",
			"field2": "2.0"
		},
		{
			"created_at": "2018-02-02 11:27:27 -0500",
			"field1": "1.1",
			"field2": "2.2",
			"status": "well done"
		}
	]
}

Specify Time Format delta_t

{
	"write_api_key": "WRITE_API_KEY",
	"updates": [{
			"delta_t": 4,
			"field1": 1.0,
			"field2": "2.0"
		},
		{
			"delta_t": 2,
			"field1": 1.1,
			"field2": 2.2,
			"elevation": 6,
			"status": "Good"
		}
	]
}

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 should be 15 seconds or more.

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

• All objects in the updates array 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

Create a Bulk Write POSTMAN Request with Absolute Timestamps

You can configure POSTMAN to try RESTful API calls. To send an HTTP POST request to bulk-update a channel feed using a JSON object, configure the POSTMAN as shown:

1. In the Headers tab, set the Content-Type as application/json.

   

2. Set the Body of the request as a raw JSON object, and enter the JSON object in POSTMAN.

   

   The format for the complete POST is shown here.

   POST /channels/999900/bulk_update.json HTTP/1.1
   Host: api.thingspeak.com
   Content-Type: application/json
   {
   	"write_api_key": "JNWIVP3CD54ZGI9X",
   	"updates": [{
   			"created_at": "2018-01-30 10:26:2 -0500",
   			"field1": 100
   		},
   		{
   			"created_at": "2017-01-30 10:26:23 -0500",
   			"field1": "red",
   			"field2": "blue",
   			"field3": "green",
   			"field4": "fish",
   			"field5": "alimony",
   			"field6": 100,
   			"field7": 100,
   			"field8": 100,
   			"status": "good"
   		},
   		{
   			"created_at": "2018-01-30 10:26:26 -0500",
   			"field1": 1500,
   			"field2": 150,
   			"field3": 100,
   			"field4": 100,
   			"field5": 100,
   			"field6": 100,
   			"field7": 100,
   			"field8": 100,
   			"latitude": 123,
   			"longitude": 23,
   			"elevation": 34
   		}
   	]
   }

3. The response is a JSON object indicating success.

   

Bulk-Write with Relative Timestamps

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

Enter the POST code. The exact process and format varies depending on your client.

POST /channels/999900/bulk_update.json HTTP/1.1
Host: api.thingspeak.com
Content-Type: application/json
{
	"write_api_key": "XXXXXXXXXXXXXXXX",
	"updates": [{
			"delta_t": "0",
			"field1": 100
		},
		{
			"delta_t": "2",
			"field1": "200"
		},
		{
			"delta_t": "1",
			"field1": 103
		},
		{
			"delta_t": "2",
			"field1": "23"
		},
		{
			"delta_t": "1",
			"field1": 86
		},
		{
			"delta_t": "5",
			"field1": "201"
		}
	]
}

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. 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.