Read Field

Read data from a single field of a channel with HTTP GET

Request

HTTP Method

GET

URL

https://api.thingspeak.com/channels/<channel_id>/fields/<field_id>.<format>

URL Parameters

Name	Description
<channel_id>	(Required) Channel ID for the channel of interest, specified as an integer.
<field_id>	(Required) Field ID for the channel of interest.
<format>	(Required) Format for the HTTP response, specified as json, xml, or csv.

Example: https://api.thingspeak.com/channels/266256/fields/2.json

Query String Parameters

Name	Description	Value Type
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
results	(Optional) Number of entries to retrieve. The maximum number is 8000.	integer
days	(Optional) Number of 24-hour periods before now to include in response. The default is 1.	integer
minutes	(Optional) Number of 60-second periods before now to include in response. The default is 1440.	integer
start	(Optional) Start date in format YYYY-MM-DD%20HH:NN:SS.	datetime
end	(Optional) End date in format YYYY-MM-DD%20HH:NN:SS.	datetime
timezone	(Optional) Identifier from Time Zones Reference for this request.	string
offset	(Optional) Timezone offset that results are displayed in. Use the timezone parameter for greater accuracy.	integer
status	(Optional) Include status updates in feed by setting "status=true".	true or false
metadata	(Optional) Include metadata for a channel by setting "metadata=true".	true or false
location	(Optional) Include latitude, longitude, and elevation in feed by setting "location=true".	true or false
min	(Optional) Minimum value to include in response.	true or false
max	(Optional) Maximum value to include in response.	decimal
round	(Optional) Round to this many decimal places.	integer
timescale	(Optional) Get first value in this many minutes, valid values: 10, 15, 20, 30, 60, 240, 720, 1440, "daily".	integer or string
sum	(Optional) Get sum of this many minutes, valid values: 10, 15, 20, 30, 60, 240, 720, 1440, "daily".	integer or string
average	(Optional) Get average of this many minutes, valid values: 10, 15, 20, 30, 60, 240, 720, 1440, "daily".	integer or string
median	(Optional) Get median of this many minutes, valid values: 10, 15, 20, 30, 60, 240, 720, 1440, "daily".	integer or string

Tip

The results parameter has the highest precedence. Using results with the parameters min, max, timescale, sum, average, or median can cause less than 8000 records to be returned. The results parameter determines the maximum number of entries to be used for a query, up to 8000. For example, consider a channel with one update per minute. A read request to that channel with the parameters ?results=120&sum=60 returns only two records, and not 120. See the example Read Two Hours of Entries in JSON Format and Average.

Examples

You can use your web browser to complete GET HTTP requests to the RESTful API for ThingSpeak™. To see the format for an HTTP response, click the link or copy it to your browser.

Read 10 Results in JSON Format

Channel 9 contains information from several home environment sensors. You can read data from the individual fields of this public channel. The format for the response occurs at the end of the URL, before any query string parameters. Here the requested format is json. Append the first parameter after a question mark ?. You can use the results parameter to control the number of entries returned, which is up to 8000.

https://api.thingspeak.com/channels/9/fields/1.json?results=10

Read Median Value every 10 Minutes for 100 Results in XML Format

In this example, the format is specified as XML. The results parameter is used to return a specified number of entries, in this case 10.

https://api.thingspeak.com/channels/9/fields/2.xml?results=100&median=10

Read a Date Range of Events in CSV Format

When you request the output in csv format, the file returned is a comma-separated variable format. Depending on your computer configuration, your browser can open additional software to display this format. Use the ampersand & to append the second parameter. In this example, the start and end parameters are used to specify date limits for the requested data.

https://api.thingspeak.com/channels/9/fields/1.csv?start=2011-11-11%2010:10:10&end=2011-11-11%2011:11:11

Read One Day of Results in Text Format

https://api.thingspeak.com/channels/9/fields/1?api_key=E52AWRAV1RSXQQJW

ThingSpeak returns the last day of data, up to 8000 points, when no other parameter is specified.

Response

Success

HTTP Status Code

200 OK

If you do not have access to the channel, the response is -1.

Body

 JSON Example

GET https://api.thingspeak.com/channels/9/fields/1.json?results=2 or GET https://api.thingspeak.com/channels/9/fields/1?results=2 or

The response is a JSON object of the channel field feed, for example: { "channel": { "id": 9, "name": "my_house", "description": "Netduino Plus connected to sensors around the house", "latitude": "40.44", "longitude": "-79.9965", "field1": "Light", "field2": "Outside Temperature", "created_at": "2010-12-14T01:20:06Z", "updated_at": "2018-01-26T13:35:04Z", "last_entry_id": 13633291 }, "feeds": [ { "created_at": "2018-01-26T13:34:48Z", "entry_id": 13633290, "field1": "160" }, { "created_at": "2018-01-26T13:35:04Z", "entry_id": 13633291, "field1": "167" } ] }

 XML Example

GET https://api.thingspeak.com/channels/9/feeds.xml?results=2

The response is an XML object of the channel field feed, for example: <channel> <id type="integer">9</id> <name>my_house</name> <description> Netduino Plus connected to sensors around the house </description> <latitude type="decimal">40.44</latitude> <longitude type="decimal">-79.9965</longitude> <field1>Light</field1> <field2>Outside Temperature</field2> <created-at type="dateTime">2010-12-14T01:20:06Z</created-at> <updated-at type="dateTime">2018-01-26T13:35:04Z</updated-at> <last-entry-id type="integer">13633291</last-entry-id> <feeds type="array"> <feed> <created-at type="dateTime">2018-01-26T13:34:48Z</created-at> <entry-id type="integer">13633290</entry-id> <field1>160</field1> <id type="integer" nil="true"/> </feed> <feed> <created-at type="dateTime">2018-01-26T13:35:04Z</created-at> <entry-id type="integer">13633291</entry-id> <field1>167</field1> <id type="integer" nil="true"/> </feed> </feeds> </channel>

 CSV Example

GET https://api.thingspeak.com/channels/9/feeds.csv?results=2

The response is a CSV object of the channel field feed, for example: created_at,entry_id,field1 2018-01-26 13:36:03 UTC,13633294,159 2018-01-26 13:36:19 UTC,13633295,177

Error

For the full list, see Error Codes.

If you do not have access to the channel, the response is -1.