ThingSpeak API

Updated ThingSpeak Documentation is now located in ThingSpeak Docs. For support, use the ThingSpeak Forum.

ThingSpeak API

Keywords

Here are some keywords that are used in the API. An understanding of the terms will make the API documentation easier to understand.

Channel – The name for where data can be inserted or retrieved within the ThingSpeak API, identified by a numerical Channel ID
Field – One of eight specific locations for data inside of a channel, identified by a number between 1 to 8 – A field can store numeric data from sensors or alphanumeric strings from serial devices or RFID readers
Status – A short status message to augment the data stored in a channel
Location – The latitude, longitude, and elevation of where data is being sent from
Feed – The collective name for the data stored inside a channel, which may be any combination of field data, status updates, and location info
Write API Key – A 16 digit code that allows an application to write data to a channel
Read API Key – A 16 digit code that allows an application to read the data stored in a channel

Addresses and Locations

Regular URL: [cce]http://api.thingspeak.com[/cce]
Secure URL: [cce]https://api.thingspeak.com[/cce]
IP Address: [cce]http://184.106.153.149[/cce]
Cross-domain XML: [cce]http://api.thingspeak.com/crossdomain.xml[/cce]

Write API Key

In order to update a channel, you need to know your Write API Key. If your Write API Key gets compromised you can generate a new key.
Follow these steps to get your Write API Key:

Select Channels
Select the Channel to update
Select Manage API Keys

Read API Key

The Read API Key allows your application to read data from the API. You can generate multiple Read API Keys for different applications.
Follow these steps to get a Read API Key:

Select Channels
Select the Channel to update
Select Manage API Keys
Select Generate New Read API Key

Channel ID

Every channel has a unique Channel ID. The Channel ID number is used to identify the channel when your application reads data from the channel.

Private/Public Channels

By default, your channel is private and requires a Read API Key to access its feed. You can make a channel public which gives other users the ability to use your feed without a Read API Key.

API Rate Limit

The open service via ThingSpeak.com has a rate limit of an update per channel every 15 seconds. This limit is so that the service can remain free and give everyone a high-level of service. The API source will also be made available on GitHub so that you can run this locally or via a shared web host provider. At that point you will be able to to tweak settings for your application requirements.

Caching

Caching is implemented on JSON and XML formats on feeds. Feeds that return more than 100 entries are cached for 5 minutes. This will allow great performance for popular applications. The Last API call and feeds that specify “results=100” or less are not cached, so that you can produce real-time applications.

Updating a Channel

Method: POST or GET
Update URL:
[cce]http://api.thingspeak.com/update[/cce]
Required Parameter:

key=[Write API Key]

Optional Field Parameters:

field1=[Field 1 Data]
field2=[Field 2 Data]
field3=[Field 3 Data]
field4=[Field 4 Data]
field5=[Field 5 Data]
field6=[Field 6 Data]
field7=[Field 7 Data]
field8=[Field 8 Data]

Optional Location Parameters:

lat=[Latitude in decimal degrees]
long=[Longitude in decimal degrees]
elevation=[Elevation in meters]

Optional Status Parameter:

status=[Status Update]

Optional Twitter Parameters:

twitter=[Twitter Username linked to ThingTweet]
tweet=[Twitter Status Update]

Reply: If the update is successful, the API will respond with the entry_id of the update. If the response is “0” then the update failed.

Example HTTP POST

[cce]POST /update HTTP/1.1
Host: api.thingspeak.com
Connection: close
X-THINGSPEAKAPIKEY: (Write API Key)
Content-Type: application/x-www-form-urlencoded
Content-Length: (number of characters in message)
field1=(Field 1 Data)&field2=(Field 2 Data)&field3=(Field 3 Data)&field4=(Field 4 Data)&field5=(Field 5 Data)&field6=(Field 6 Data)&field7=(Field 7 Data)&field8=(Field 8 Data)&lat=(Latitude in Decimal Degrees)&long=(Longitude in Decimal Degrees)&elevation=(Elevation in meters)&status=(140 Character Message)[/cce]

Feed Formats

When retrieving data from a channel feed, you may specify one of the following formats:

json
xml
csv

Retrieving Channel Feeds

Method: GET
Feed URL:
[cce]http://api.thingspeak.com/channels/(channel_id)/feed.(format)[/cce]
Optional Parameters:

key=[Read API Key] – no key required for public channels
results=[number of entries to retrieve (8000 max)]
days=[days from now to include in feed]
start=[start date] – YYYY-MM-DD%20HH:NN:SS
end=[end date] – YYYY-MM-DD%20HH:NN:SS
offset=[timezone offset in hours]
status=true (include status updates in feed)
location=true (include latitude, longitude, and elevation in feed)
min=[minimum value to include in response]
max=[maximum value to include in response]
round=x (round to x decimal places)
timescale=x (get first value in x minutes, valid values: 10, 15, 20, 30, 60, 240, 720, 1440)
sum=x (get sum of x minutes, valid values: 10, 15, 20, 30, 60, 240, 720, 1440)
average=x (get average of x minutes, valid values: 10, 15, 20, 30, 60, 240, 720, 1440)
median=x (get median of x minutes, valid values: 10, 15, 20, 30, 60, 240, 720, 1440)
callback=[function name] (used for JSONP cross-domain requests)

Examples:

Retrieving the Last Entry in Channel Feed

Method: GET
Feed URL:
[cce]http://api.thingspeak.com/channels/(channel_id)/feed/last.(format)[/cce]
Optional Parameters:

key=[Read API Key]
offset=[timezone offset in hours]
status=true (include status updates in feed)
location=true (include latitude, longitude, and elevation in feed)
callback=[function name] (used for JSONP cross-domain requests)

Retrieving a Field Feed

Method: GET
Feed URL:
[cce]http://api.thingspeak.com/channels/(channel_id)/field/(field_id).(format)[/cce]
Optional Parameters:

key=[Read API Key]
results=[number of entries to retrieve (8000 max)]
days=[days to include in feed]
start=[start date] – YYYY-MM-DD%20HH:NN:SS
end=[end date] – YYYY-MM-DD%20HH:NN:SS
offset=[timezone offset in hours]
status=true (include status updates in feed)
location=true (include latitude, longitude, and elevation in feed)
min=[minimum value to include in response]
max=[maximum value to include in response]
round=x (round to x decimal places)
timescale=x (get first value in x minutes, valid values: 10, 15, 20, 30, 60, 240, 720, 1440)
sum=x (get sum of x minutes, valid values: 10, 15, 20, 30, 60, 240, 720, 1440)
average=x (get average of x minutes, valid values: 10, 15, 20, 30, 60, 240, 720, 1440)
median=x (get median of x minutes, valid values: 10, 15, 20, 30, 60, 240, 720, 1440)
callback=[function name] (used for JSONP cross-domain requests)

Retrieving the Last Entry in a Field Feed

Method: GET
Feed URL:
[cce]http://api.thingspeak.com/channels/(channel_id)/field/(field_id)/last.(format)[/cce]
Optional Parameters:

key=[Read API Key]
offset=[timezone offset in hours]
status=true (include status updates in feed)
location=true (include latitude, longitude, and elevation in feed)
callback=[function name] (used for JSONP cross-domain requests)

Optional Format:

Optional Parameters for TXT format:

prepend=[text to add before the API response]
append=[text to add after the API response]

Retrieving Status Updates

Method: GET
Feed URL:
[cce]http://api.thingspeak.com/channels/(channel_id)/status.(format)[/cce]
Optional Parameters:

key=[Read API Key]
offset=[timezone offset in hours]
callback=[function name] (used for JSONP cross-domain requests)

Listing Public Channels

Method: GET
Public Channels URL:
[cce]http://api.thingspeak.com/channels/public.(format)[/cce]
Optional Parameters:

page=[page number to retrieve]
tag=[name of tag to search for, should be URL encoded]

Examples:

Listing User Information

Method: GET
User Information URL:
[cce]http://api.thingspeak.com/users/(username).(format)[/cce]
Optional Parameters:

key=[user API key]

If a user’s API key is provided, private information such as their email address will be provided.

Examples:

http://api.thingspeak.com/users/hans.json

Listing a User’s Channels

Method: GET
User’s Channels URL:
[cce]http://api.thingspeak.com/users/(username)/channels.(format)[/cce]
Optional Parameters:

key=[user API key]

If a user’s API key is provided, private channels will also be displayed.

Examples:

http://api.thingspeak.com/users/hans/channels.json

Chart API

The Chart API allows you to create an instant visualization of your data. The chart displays properly in all modern browsers and mobile devices. The chart can also show dynamic data by loading new data automatically.
Chart URL:
[cce]http://api.thingspeak.com/channels/(channel_id)/charts/(field_id)[/cce]
Optional Chart Parameters:

title=[chart title, default: channel name]
xaxis=[chart’s x-axis label, default: Date]
yaxis=[chart’s y-axis label, default: field name]
color=[line color, default: red]
bgcolor=[background color, default: white]
type=[line, bar, or column, default: line]
width=x (chart width in pixels, iframe width will be 20px larger, default chart width: 400)
height=x (chart height in pixels, iframe height will be 20px larger, default chart height: 200)
dynamic=[true or false, default: false] (make chart update automatically every 15 seconds)
step=[true or false, default: false] (draw chart as a step chart)
export=[true or false, default: false] (show export buttons, so that chart can be saved as image)

Optional Feed Parameters:

key=[Read API Key]
results=[number of entries to retrieve (8000 max)]
days=[days to include in feed]
start=[start date] – YYYY-MM-DD%20HH:NN:SS
end=[end date] – YYYY-MM-DD%20HH:NN:SS
offset=[timezone offset in hours]
status=true (include status updates in feed)
location=true (include latitude, longitude, and elevation in feed)
min=[minimum value to include in response]
max=[maximum value to include in response]
round=x (round to x decimal places)
timescale=x (get first value in x minutes, valid values: 10, 15, 20, 30, 60, 240, 720, 1440)
sum=x (get sum of x minutes, valid values: 10, 15, 20, 30, 60, 240, 720, 1440)
average=x (get average of x minutes, valid values: 10, 15, 20, 30, 60, 240, 720, 1440)
median=x (get median of x minutes, valid values: 10, 15, 20, 30, 60, 240, 720, 1440)

Embedding a Chart

To place a ThingSpeak Chart on your webpage, use the Chart API as the source of an iframe.
Chart Embed Code:
[cce]<iframe width=”450″ height=”250″ style=”border: 1px solid #cccccc;” src=”http://thingspeak.com/channels/(channel_id)/charts/(field_id)”></iframe>[/cce]
Example Chart:
[iframe_loader src=”https://thingspeak.com/channels/3/charts/1″]
Embedding a Dynamic Chart
To place a dynamic ThingSpeak Chart on your webpage, use the Chart API as the source of an iframe and add the chart parameter “dynamic=true”.
Chart Embed Code:
[cce]<iframe width=”450″ height=”250″ style=”border: 1px solid #cccccc;” src=”http://thingspeak.com/channels/(channel_id)/charts/(field_id)?dynamic=true”></iframe>[/cce]
Example Chart:
[iframe_loader src=”https://thingspeak.com/channels/9/charts/1?dynamic=true&results=15&title=Dynamic+Light+Levels”]

19 comments

tz says:

April 14, 2011 at 7:27 pm

Why doesn’t the following save location?
http://api.thingspeak.com/update?key=***&lat=40&long=-80&elevation=200
It responds with an entry ID but there is no location data when I read it. Or do I need something special to do read beside
http://api.thingspeak.com/channels/352/feed.json?key=****
1. thingspeak says:
  
  April 14, 2011 at 7:30 pm
  
  By default location and status are hidden from the feed. To display the location add the parameter, “location=true”, and to display status updates add the parameter, “status=true”.
  1. Martin Bogomolni says:
    
    August 21, 2014 at 1:12 am
    
    Device Discovery + ThingSpeak
    I need to store and retrieve API keys using the user credentials to do automatic device discovery. Is there a mechanism in ThingSpeak that will allow me to retrieve the Read and the Write API key for a channel using a RESTful call if I have the username/password credentials?
    Basically, I need a fully automated way, without human intervention, to be able to do integration.
    Sincerely,
    Martin
    1. lee says:
      
      August 21, 2014 at 9:36 pm
      
      Hi Martin,
      Yes it is possible to RESTfully retrieve your API keys for a Channel. Please see the documentation section “List My Channels” here: https://thingspeak.com/docs/channels#index .
      lee
2. Alessio says:
  
  November 10, 2014 at 2:15 am
  
  Hi everyone,
  I have the same issue about the location attribute.
  There is no location data when I read it but after data upload.
  I send out a string like this one:
  field1=22.9&field2=47.0&field3=0.0&field4=11.3&field5=6.9&field6=33.4&field7=8.3&field8=0.0&key=**************&lat=25.375852&long=51.490664&elevation=19&status=SeReNo+first+prototype+under+test
  What’s the problem about the location data uploading?
  1. lee says:
    
    November 10, 2014 at 8:35 am
    
    Hi Alessio,
    What URL are you using to read your Channel feed? Are you including “location=true” as a parameter when reading your Channel feed?
    lee
tz says:

April 15, 2011 at 11:34 am

That helped, but how well do you filter the input? Doing
…field1=”}]}
gave
…
{
created_at: “2011-04-15T15:51:45Z”
entry_id: 9
field1: “”}]}”
}
]
}
(end)
Now I probably don’t want to see what I could do if this was sent to eval().
1. tz says:
  
  April 15, 2011 at 11:50 am
  
  ok – firefox or one of my extensions was formatting things (wrongly) for me. It is escaping things internally correctly
ricardo_ati says:

November 7, 2011 at 2:39 am

Hi all.
I am using successfully ThingSpeak, great tool. I have a question.
Trying to replace a bad value, I write it again with “created_at” and I have the new value with the specified time and date with a new “entry_id” (I can see it in the CSV file).
I tried sending also an “entry_id” to replace the original value that is wrong, but the CSV file maintains two records with the same “created_at” and different entry_id”.
Is it possible to replace an existing record?
1. thingspeak says:
  
  November 7, 2011 at 2:45 am
  
  Thanks for the comments!
  As of right now, you can’t override a previous data point using an API call. If you don’t mind, add that request to the “Feature Requests” on the forum. We will consider adding that in ThingSpeak 2.0.
pereskjo says:

May 16, 2012 at 3:09 am

“VALUE NOW” ON DYNAMIC CHART:
I like this chart, but I think its to hard and time consuming to read a exact “Value Now” for the latest incoming value.
Is it Possible you can implement a “Value Now” in big clear Letters on the chart?
Your other competitors have this function.
Please let me know if there is other ways to do this.
1. Hans says:
  
  August 14, 2012 at 11:06 am
  
  The value now display is a good idea. We will note it in the feature requests list.
  What we are working on now is a new plugin system that will allow you to make customizations to ThingSpeak. This would be perfect for requests like this.
  You will also be able to add the Plugins to your Private and Public views.
EvoIce says:

June 28, 2012 at 9:12 pm

Is there any documentation on how to create the charts?
1. Hans says:
  
  June 29, 2012 at 12:45 am
  
  The charts get created automatically when you send data to ThingSpeak.
  You access the charts with the Charts API or when you log into ThingSpeak, select your Channel.
  http://community.thingspeak.com/documentation/api/#charts
Bart says:

January 7, 2013 at 6:39 pm

Just new and had a look and tested the API.
Everything seems to work as documented.
However how can an application (microcontroller) update missing data if a crash has happend (on the microcontroller)?
I can upload CSV (history) data myself and that works, but looking at the API and parameters there are no parameters/datafields for date and time.
I hope this is possible via the Updating a Channel “Get” method.
1. Dustin says:
  
  February 7, 2013 at 7:07 am
  
  Yeah, that might be a cool feature. Something like: field1=1&datetime=2013-02-17T12:06:03Z
2. Sean says:
  
  August 16, 2013 at 1:28 pm
  
  There seems to be an undocumented HTTP parameter which allows this: “created_at=2013-02-05T21:49:00+01:00”.
Oliver says:

February 19, 2014 at 7:00 pm

Hi all;
I have some questions related with charts visualization.
Is there any way to see any chart in my web page without making public my channel? I would like whoever enter in my web-site can watch my charts.
Can I store my access token in my web-page in any way?
Thanks all.
Oliver
peter says:

December 11, 2014 at 10:04 pm

Hi all ;
I want to send my phone gps to thingspeak .
I send my gps but I don’t no how to take my gps data from ThingSpeak.
How can I do ?

Comments are closed.