API

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:

http://api.thingspeak.com

Secure URL:

https://api.thingspeak.com

IP Address:

http://184.106.153.149

Cross-domain XML:

http://api.thingspeak.com/crossdomain.xml

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:

http://api.thingspeak.com/update

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

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:

http://api.thingspeak.com/channels/(channel_id)/feed.(format)

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:

http://api.thingspeak.com/channels/(channel_id)/feed/last.(format)

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:

http://api.thingspeak.com/channels/(channel_id)/field/(field_id).(format)

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:

http://api.thingspeak.com/channels/(channel_id)/field/(field_id)/last.(format)

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:

  • txt

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:

http://api.thingspeak.com/channels/(channel_id)/status.(format)

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:

http://api.thingspeak.com/channels/public.(format)

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:

http://api.thingspeak.com/users/(username).(format)

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:

Listing a User’s Channels

Method: GET

User’s Channels URL:

http://api.thingspeak.com/users/(username)/channels.(format)

Optional Parameters:

  • key=[user API key]

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

Examples:

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:

http://api.thingspeak.com/channels/(channel_id)/charts/(field_id)

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:

<iframe width="450" height="250" style="border: 1px solid #cccccc;" src="http://thingspeak.com/channels/(channel_id)/charts/(field_id)"></iframe>

Example Chart:

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:

<iframe width="450" height="250" style="border: 1px solid #cccccc;" src="http://thingspeak.com/channels/(channel_id)/charts/(field_id)?dynamic=true"></iframe>

Example Chart:

  • Twitter
  • Facebook
  • Google Bookmarks
  • del.icio.us
  • StumbleUpon
  • Reddit
  • Digg
  • Add to favorites

14 comments

  1. 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=****

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

  2. 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().

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

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

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

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

  5. Is there any documentation on how to create the charts?

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

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

Leave a comment