Documentation

This is machine translation

Translated by Microsoft
Mouseover text to see original. Click the button below to return to the English version of the page.

Note: This page has been translated by MathWorks. Click here to see
To view all translated materials including this page, select Country from the country navigator on the bottom of this page.

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

NameDescription

<channel_id>

(Required) Channel ID for the channel of interest.

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

Body Parameters / Object Members

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

NameDescriptionValue-Type
write_api_key

(Required for private channels) Specify Read API Key for this specific channel. The Read API Key is found on the API Keys tab of the channel view.

<string>

updates

(Required) Specify array of updates to your channel.

<array> of JSON objects with members shown in Updates

Updates

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

NameDescriptionValue-Type
created_at

(Required unless delta_t included) absolute time of the event in ISO 8601, EPOCH, or MYSQL formats. Must be unique within channel.

<string>
delta_t

(Required unless created_at included) Specify time between measurements with delta_t.

<string>
field<X>

(Optional) Field X data, where X is the field ID.

<any>

latitude

(Optional) Latitude in degrees.

<number>

longitude

(Optional) Longitude in degrees.

<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

collapse all

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.

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.