Channels

Channels are where your application stores and retrieves any type of data. Each channel has a Private View and a Public View. The Private View is only accessible by signing into your ThingSpeak.com user account. The Public View is what other viewers will see when they visit your ThingSpeak Channel. You can have different info on each view, customize the view with Plugins, and even disable the Public View.



Channel public view


Channel Views have the following features:

  • Channel Watch
  • Share via Social Networks
  • Developer Info
  • Ability to embed ThingSpeak Plugins
  • Drag-and-drop Organization
  • Tags
  • Comments


Channels API

To read and write to a ThingSpeak Channel, your application must make requests to the ThingSpeak API using HTTP requests. Each ThingSpeak Channel allows for 8 fields of data (both numeric and alphanumeric formats), location information, and a status update. Each entry is stored with a date and time stamp and is assigned a unique Entry ID (entry_id). After the data is stored, you can retrieve the data by time selection or by Entry ID. In addition to storing and retrieving numeric and alphanumeric data, the ThingSpeak API allows for numeric data processing such as timescaling, averaging, median, summing, and rounding. The channel feeds supports JSON, XML, and CSV formats for integration into applications.


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



Base URL 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



API Keys



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.


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




Rate Limits

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.














Response in: TEXTJSONXML

Update Channel Feed


To update a Channel feed, send an HTTP GET or POST to
https://127.0.0.1:3000/update.json.xml .

Valid parameters:
  • api_key (string) - Write API Key for this specific Channel (required). The Write API Key can optionally be sent via a THINGSPEAKAPIKEY HTTP header.
  • field1 (string) - Field 1 data (optional)
  • field2 (string) - Field 2 data (optional)
  • field3 (string) - Field 3 data (optional)
  • field4 (string) - Field 4 data (optional)
  • field5 (string) - Field 5 data (optional)
  • field6 (string) - Field 6 data (optional)
  • field7 (string) - Field 7 data (optional)
  • field8 (string) - Field 8 data (optional)
  • lat (decimal) - Latitude in degrees (optional)
  • long (decimal) - Longitude in degrees (optional)
  • elevation (integer) - Elevation in meters (optional)
  • status (string) - Status update message (optional)
  • twitter (string) - Twitter username linked to ThingTweet (optional)
  • tweet (string) - Twitter status update; see updating ThingTweet for more info (optional)
  • created_at (datetime) - Date when this feed entry was created, in ISO 8601 format, for example: 2014-12-31 23:59:59 . Time zones can be specified via the timezone parameter (optional)

Example POST:
POST https://127.0.0.1:3000/update.json.xml
     api_key=XXXXXXXXXXXXXXXX
     field1=73

The response will be the entry ID of the update, for example: 18

If the response is 0 then the update failed.
The response will be a JSON object of the new feed, for example:
{
  "channel_id": 3,
  "field1": "73",
  "field2": null,
  "field3": null,
  "field4": null,
  "field5": null,
  "field6": null,
  "field7": null,
  "field8": null,
  "created_at": "2014-02-25T14:13:01-05:00",
  "entry_id": 320,
  "status": null,
  "latitude": null,
  "longitude": null,
  "elevation": null
}
The response will be an XML object of the new feed, for example:
<?xml version="1.0" encoding="UTF-8"?>
<feed>
  <channel-id type="integer">3</channel-id>
  <field1>73</field1>
  <field2 nil="true"/>
  <field3 nil="true"/>
  <field4 nil="true"/>
  <field5 nil="true"/>
  <field6 nil="true"/>
  <field7 nil="true"/>
  <field8 nil="true"/>
  <created-at type="dateTime">2014-02-25T14:15:42-05:00</created-at>
  <entry-id type="integer">321</entry-id>
  <status nil="true"/>
  <latitude type="decimal" nil="true"/>
  <longitude type="decimal" nil="true"/>
  <elevation nil="true"/>
</feed>

Response in: TEXTJSONXML

Get a Channel Feed


To view a Channel feed, send an HTTP GET to https://127.0.0.1:3000/channels/CHANNEL_ID/feeds.json.xml , replacing CHANNEL_ID with the ID of your Channel.

Valid parameters:
  • api_key (string) Read API Key for this specific Channel (optional--no key required for public channels)
  • results (integer) Number of entries to retrieve, 8000 max, default of 100 (optional)
  • days (integer) Number of 24-hour periods before now to include in feed (optional)
  • start (datetime) Start date in format YYYY-MM-DD%20HH:NN:SS (optional)
  • end (datetime) End date in format YYYY-MM-DD%20HH:NN:SS (optional)
  • timezone (string) Timezone identifier for this request (optional)
  • offset (integer) Timezone offset that results should be displayed in. Please use the timezone parameter for greater accuracy. (optional)
  • status (true/false) Include status updates in feed by setting "status=true" (optional)
  • metadata (true/false) Include Channel's metadata by setting "metadata=true" (optional)
  • location (true/false) Include latitude, longitude, and elevation in feed by setting "location=true" (optional)
  • min (decimal) Minimum value to include in response (optional)
  • max (decimal) Maximum value to include in response (optional)
  • round (integer) Round to this many decimal places (optional)
  • timescale (integer or string) Get first value in this many minutes, valid values: 10, 15, 20, 30, 60, 240, 720, 1440, "daily" (optional)
  • sum (integer or string) Get sum of this many minutes, valid values: 10, 15, 20, 30, 60, 240, 720, 1440, "daily" (optional)
  • average (integer or string) Get average of this many minutes, valid values: 10, 15, 20, 30, 60, 240, 720, 1440, "daily" (optional)
  • median (integer or string) Get median of this many minutes, valid values: 10, 15, 20, 30, 60, 240, 720, 1440, "daily" (optional)
  • callback (string) Function name to be used for JSONP cross-domain requests (optional)
Please note that the results parameter is not compatible with timescale, sum, average, or median.

Example GET:
GET https://127.0.0.1:3000/channels/9/feeds.json.xml?results=2

The response will be an HTML page with the JSON Channel feed, for example:
{
  "channel":
  {
    "id": 9,
    "name": "my_house",
    "description": "Netduino Plus connected to sensors around the house",
    "latitude": "40.44",
    "longitude": "-79.996",
    "field1": "Light",
    "field2": "Outside Temperature",
    "created_at": "2010-12-13T20:20:06-05:00",
    "updated_at": "2014-02-26T12:43:04-05:00",
    "last_entry_id": 6060625
  },
  "feeds":
  [
    {
      "created_at": "2014-02-26T12:42:49-05:00",
      "entry_id": 6060624,
      "field1": "188",
      "field2": "25.902335456475583"
    },
    {
      "created_at": "2014-02-26T12:43:04-05:00",
      "entry_id": 6060625,
      "field1": "164",
      "field2": "25.222929936305732"
    }
  ]
}
The response will be a JSON object of the Channel feed, for example:
{
  "channel":
  {
    "id": 9,
    "name": "my_house",
    "description": "Netduino Plus connected to sensors around the house",
    "latitude": "40.44",
    "longitude": "-79.996",
    "field1": "Light",
    "field2": "Outside Temperature",
    "created_at": "2010-12-13T20:20:06-05:00",
    "updated_at": "2014-02-26T12:43:04-05:00",
    "last_entry_id": 6060625
  },
  "feeds":
  [
    {
      "created_at": "2014-02-26T12:42:49-05:00",
      "entry_id": 6060624,
      "field1": "188",
      "field2": "25.902335456475583"
    },
    {
      "created_at": "2014-02-26T12:43:04-05:00",
      "entry_id": 6060625,
      "field1": "164",
      "field2": "25.222929936305732"
    }
  ]
}
The response will be an XML object of the Channel feed, for example:
<?xml version="1.0" encoding="UTF-8"?>
<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.996</longitude>
  <field1>Light</field1>
  <field2>Outside Temperature</field2>
  <created-at type="dateTime">2010-12-13T20:20:06-05:00</created-at>
  <updated-at type="dateTime">2014-02-26T12:49:19-05:00</updated-at>
  <last-entry-id type="integer">6060650</last-entry-id>
  <feeds type="array">
    <feed>
      <created-at type="dateTime">2014-02-26T12:49:04-05:00</created-at>
      <entry-id type="integer">6060649</entry-id>
      <field1>160</field1>
      <field2>25.307855626326962</field2>
      <id type="integer" nil="true"/>
    </feed>
    <feed>
      <created-at type="dateTime">2014-02-26T12:49:19-05:00</created-at>
      <entry-id type="integer">6060650</entry-id>
      <field1>171</field1>
      <field2>22.929936305732483</field2>
      <id type="integer" nil="true"/>
    </feed>
  </feeds>
</channel>

Live examples:

Response in: TEXTJSONXML

Get Last Entry in a Channel Feed


To get the last entry in a Channel feed, send an HTTP GET to https://127.0.0.1:3000/channels/CHANNEL_ID/feeds/last.json.xml , replacing CHANNEL_ID with the ID of your Channel.

Valid parameters:
  • api_key (string) Read API Key for this specific Channel (optional--no key required for public channels)
  • timezone (string) Timezone identifier for this request (optional)
  • offset (integer) Timezone offset that results should be displayed in. Please use the timezone parameter for greater accuracy. (optional)
  • status (true/false) Include status updates in feed by setting "status=true" (optional)
  • location (true/false) Include latitude, longitude, and elevation in feed by setting "location=true" (optional)
  • callback (string) Function name to be used for JSONP cross-domain requests (optional)

Example GET:
GET https://127.0.0.1:3000/channels/9/feeds/last.json.xml

The response will be a JSON object of the most recent feed, for example:
{
  "created_at": "2014-02-26T21:27:21Z",
  "entry_id": 6061519,
  "field1": "176",
  "field2": "28.195329087048833"
}
The response will be a JSON object of the most recent feed, for example:
{
  "created_at": "2014-02-26T21:27:21Z",
  "entry_id": 6061519,
  "field1": "176",
  "field2": "28.195329087048833"
}
The response will be an XML object of the most recent feed, for example:
<?xml version="1.0" encoding="UTF-8"?>
<feed>
  <created-at type="dateTime">2014-02-26T21:28:51Z</created-at>
  <entry-id type="integer">6061525</entry-id>
  <field1>200</field1>
  <field2>28.365180467091296</field2>
  <id type="integer" nil="true"/>
</feed>


Response in: TEXTJSONXML

Get Specific Entry in a Channel


To get a specific entry in a Channel's feed, send an HTTP GET to https://127.0.0.1:3000/channels/CHANNEL_ID/feeds/ENTRY_ID.json.xml , replacing CHANNEL_ID with the ID of your Channel and ENTRY_ID with the ID of your entry.

Valid parameters:
  • api_key (string) Read API Key for this specific Channel (optional--no key required for public channels)
  • timezone (string) Timezone identifier for this request (optional)
  • offset (integer) Timezone offset that results should be displayed in. Please use the timezone parameter for greater accuracy. (optional)
  • status (true/false) Include status updates in feed by setting "status=true" (optional)
  • location (true/false) Include latitude, longitude, and elevation in feed by setting "location=true" (optional)
  • callback (string) Function name to be used for JSONP cross-domain requests (optional)

Example GET:
GET https://127.0.0.1:3000/channels/9/feeds/6061519.json.xml

The response will be a JSON object of the feed entry, for example:
{
  "created_at": "2014-02-26T21:27:21Z",
  "entry_id": 6061519,
  "field1": "176",
  "field2": "28.195329087048833"
}
The response will be a JSON object of the feed entry, for example:
{
  "created_at": "2014-02-26T21:27:21Z",
  "entry_id": 6061519,
  "field1": "176",
  "field2": "28.195329087048833"
}
The response will be an XML object of the most recent feed, for example:
<?xml version="1.0" encoding="UTF-8"?>
<feed>
  <created-at type="dateTime">2014-02-26T21:27:21Z</created-at>
  <entry-id type="integer">6061519</entry-id>
  <field1>176</field1>
  <field2>28.195329087048833</field2>
  <id type="integer" nil="true"/>
</feed>

Response in: TEXTJSONXML

Get a Channel Field Feed


To view a Channel's field feed, send an HTTP GET to https://127.0.0.1:3000/channels/CHANNEL_ID/fields/FIELD_ID.json.xml , replacing CHANNEL_ID with the ID of your Channel and FIELD_ID with the ID of your field.

Valid parameters:
  • api_key (string) Read API Key for this specific Channel (optional--no key required for public channels)
  • results (integer) Number of entries to retrieve, 8000 max, default of 100 (optional)
  • days (integer) Number of 24-hour periods before now to include in feed (optional)
  • start (datetime) Start date in format YYYY-MM-DD%20HH:NN:SS (optional)
  • end (datetime) End date in format YYYY-MM-DD%20HH:NN:SS (optional)
  • timezone (string) Timezone identifier for this request (optional)
  • offset (integer) Timezone offset that results should be displayed in. Please use the timezone parameter for greater accuracy. (optional)
  • status (true/false) Include status updates in feed by setting "status=true" (optional)
  • metadata (true/false) Include Channel's metadata by setting "metadata=true" (optional)
  • location (true/false) Include latitude, longitude, and elevation in feed by setting "location=true" (optional)
  • min (decimal) Minimum value to include in response (optional)
  • max (decimal) Maximum value to include in response (optional)
  • round (integer) Round to this many decimal places (optional)
  • timescale (integer or string) Get first value in this many minutes, valid values: 10, 15, 20, 30, 60, 240, 720, 1440, "daily" (optional)
  • sum (integer or string) Get sum of this many minutes, valid values: 10, 15, 20, 30, 60, 240, 720, 1440, "daily" (optional)
  • average (integer or string) Get average of this many minutes, valid values: 10, 15, 20, 30, 60, 240, 720, 1440, "daily" (optional)
  • median (integer or string) Get median of this many minutes, valid values: 10, 15, 20, 30, 60, 240, 720, 1440, "daily" (optional)
  • callback (string) Function name to be used for JSONP cross-domain requests (optional)
Please note that the results parameter is not compatible with timescale, sum, average, or median.

Example GET:
GET https://127.0.0.1:3000/channels/9/fields/1.json.xml?results=2

The response will be an HTML page with the JSON Channel's field feed, for example:
{
  "channel":
  {
    "id": 9,
    "name": "my_house",
    "description": "Netduino Plus connected to sensors around the house",
    "latitude": "40.44",
    "longitude": "-79.996",
    "field1": "Light",
    "field2": "Outside Temperature",
    "created_at": "2010-12-13T20:20:06-05:00",
    "updated_at": "2014-02-26T12:43:04-05:00",
    "last_entry_id": 6060625
  },
  "feeds":
  [
    {
      "created_at": "2014-02-26T12:42:49-05:00",
      "entry_id": 6060624,
      "field1": "188"
    },
    {
      "created_at": "2014-02-26T12:43:04-05:00",
      "entry_id": 6060625,
      "field1": "164"
    }
  ]
}
The response will be a JSON object of the Channel's field feed, for example:
{
  "channel":
  {
    "id": 9,
    "name": "my_house",
    "description": "Netduino Plus connected to sensors around the house",
    "latitude": "40.44",
    "longitude": "-79.996",
    "field1": "Light",
    "field2": "Outside Temperature",
    "created_at": "2010-12-13T20:20:06-05:00",
    "updated_at": "2014-02-26T12:43:04-05:00",
    "last_entry_id": 6060625
  },
  "feeds":
  [
    {
      "created_at": "2014-02-26T12:42:49-05:00",
      "entry_id": 6060624,
      "field1": "188"
    },
    {
      "created_at": "2014-02-26T12:43:04-05:00",
      "entry_id": 6060625,
      "field1": "164"
    }
  ]
}
The response will be an XML object of the Channel's field feed, for example:
<?xml version="1.0" encoding="UTF-8"?>
<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.996</longitude>
  <field1>Light</field1>
  <field2>Outside Temperature</field2>
  <created-at type="dateTime">2010-12-13T20:20:06-05:00</created-at>
  <updated-at type="dateTime">2014-02-26T12:49:19-05:00</updated-at>
  <last-entry-id type="integer">6060650</last-entry-id>
  <feeds type="array">
    <feed>
      <created-at type="dateTime">2014-02-26T12:49:04-05:00</created-at>
      <entry-id type="integer">6060649</entry-id>
      <field1>160</field1>
      <id type="integer" nil="true"/>
    </feed>
    <feed>
      <created-at type="dateTime">2014-02-26T12:49:19-05:00</created-at>
      <entry-id type="integer">6060650</entry-id>
      <field1>171</field1>
      <id type="integer" nil="true"/>
    </feed>
  </feeds>
</channel>


Response in: TEXTJSONXML

Get Last Entry in a Field Feed


To get the last entry in a Channel's field feed, send an HTTP GET to https://127.0.0.1:3000/channels/CHANNEL_ID/fields/FIELD_ID/last.json.xml , replacing CHANNEL_ID with the ID of your Channel and FIELD_ID with the ID of your field.

Valid parameters:
  • api_key (string) Read API Key for this specific Channel (optional--no key required for public channels)
  • timezone (string) Timezone identifier for this request (optional)
  • offset (integer) Timezone offset that results should be displayed in. Please use the timezone parameter for greater accuracy. (optional)
  • status (true/false) Include status updates in feed by setting "status=true" (optional)
  • location (true/false) Include latitude, longitude, and elevation in feed by setting "location=true" (optional)
  • callback (string) Function name to be used for JSONP cross-domain requests (optional)
  • prepend (string) Text to add before the API response (optional)
  • append (string) Text to add after the API response (optional)

Example GET:
GET https://127.0.0.1:3000/channels/9/fields/1/last.json.xml

The response will be the Channel field's most recent value, for example:
176
The response will be a JSON object of the most recent feed, for example:
{
  "created_at": "2014-02-26T21:27:21Z",
  "entry_id": 6061519,
  "field1": "176"
}
The response will be an XML object of the most recent feed, for example:
<?xml version="1.0" encoding="UTF-8"?>
<feed>
  <created-at type="dateTime">2014-02-26T21:28:51Z</created-at>
  <entry-id type="integer">6061525</entry-id>
  <field1>200</field1>
  <id type="integer" nil="true"/>
</feed>

Response in: TEXTJSONXML

Get Status Updates


To view a Channel's status updates, send an HTTP GET to https://127.0.0.1:3000/channels/CHANNEL_ID/status.json.xml , replacing CHANNEL_ID with the ID of your Channel.

Valid parameters:
  • api_key (string) Read API Key for this specific Channel (optional--no key required for public channels)
  • timezone (string) Timezone identifier for this request (optional)
  • offset (integer) Timezone offset that results should be displayed in. Please use the timezone parameter for greater accuracy. (optional)
  • callback (string) Function name to be used for JSONP cross-domain requests (optional)

Example GET:
GET https://127.0.0.1:3000/channels/1417/status.json.xml

The response will be a JSON object of Channel statuses, for example:
{
  "channel":
  {
    "name": "CheerLights",
    "latitude": "40.5",
    "longitude": "-80.22"
  },
  "feeds":
  [
    {
      "created_at": "2014-02-26T02:28:01Z",
      "entry_id": 11888,
      "status": "@cheerlights green"
    },
    {
      "created_at": "2014-02-26T22:05:31Z",
      "entry_id" :11889,
      "status": "@cheerlights blue"
    }
  ]
}
The response will be a JSON object of Channel statuses, for example:
{
  "channel":
  {
    "name": "CheerLights",
    "latitude": "40.5",
    "longitude": "-80.22"
  },
  "feeds":
  [
    {
      "created_at": "2014-02-26T02:28:01Z",
      "entry_id": 11888,
      "status": "@cheerlights green"
    },
    {
      "created_at": "2014-02-26T22:05:31Z",
      "entry_id" :11889,
      "status": "@cheerlights blue"
    }
  ]
}
The response will be an XML object of Channel statuses, for example:
<?xml version="1.0" encoding="UTF-8"?>
<channel>
  <name>CheerLights</name>
  <latitude type="decimal">40.5</latitude>
  <longitude type="decimal">-80.22</longitude>
  <feeds type="array">
    <feed>
      <created-at type="dateTime">2014-02-26T02:28:01Z</created-at>
      <entry-id type="integer">11888</entry-id>
      <status>@cheerlights green</status>
      <id type="integer" nil="true"/>
    </feed>
    <feed>
      <created-at type="dateTime">2014-02-26T22:05:31Z</created-at>
      <entry-id type="integer">11889</entry-id>
      <status>@cheerlights blue</status>
      <id type="integer" nil="true"/>
    </feed>
  </feeds>
</channel>

Response in: TEXTJSONXML

List Public Channels


To view a list of public Channels, send an HTTP GET to
https://127.0.0.1:3000/channels/public.json.xml .

Valid parameters:
  • page (integer) Page number to retrieve (optional)
  • tag (string) Name of tag to search for (optional)
  • username (string) Person's username that you want to search Channels for (optional)

You can also search for Channels within a certain distance of a location by including the following location parameters:
  • latitude (decimal) - Latitude of location in degrees. (optional)
  • longitude (decimal) - Longitude of location in degrees. (optional)
  • distance (decimal) - Distance in kilometers from location. (optional)

Example GET:
GET https://127.0.0.1:3000/channels/public.json.xml

The response will be a webpage with a list of public Channels.
The response will be a JSON object of public Channels, for example:
{
  "pagination":
  {
    "current_page": 1,
    "per_page": 15,
    "total_entries": 653
  },
  "channels":
  [
    {
      "id": 9,
      "name": "my_house",
      "description": "Netduino Plus connected to sensors around the house",
      "latitude": "40.44",
      "longitude": "-79.996",
      "created_at": "2010-12-13T20:20:06-05:00",
      "elevation": "",
      "last_entry_id": 6062691,
      "ranking" :100,
      "username":"hans",
      "tags":
      [
        {
          "id": 9,
          "name": "temp"
        },{
          "id": 25,
          "name": "light"
        }
      ]
    },
    {
      "id": 5683,
      "name": "Residential Data Points",
      "description": "Arduino Uno + Ethernet Shield",
      "latitude": "35.664548",
      "longitude": "-78.654972",
      "created_at": "2013-05-15T12:33:57-04:00",
      "elevation": "100",
      "last_entry_id": 731713,
      "ranking": 100,
      "username": "samlro",
      "tags":
      [
        {
          "id": 950,
          "name": "Analog Inputs"
        }
      ]
    }
  ]
}
The response will be an XML object of public Channels, for example:
<?xml version="1.0" encoding="UTF-8"?>
<response>
  <pagination>
    <current-page type="WillPaginate::PageNumber">1</current-page>
    <per-page type="integer">15</per-page>
    <total-entries type="integer">654</total-entries>
  </pagination>
  <channels type="array">
    <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.996</longitude>
      <created-at type="dateTime">2010-12-13T20:20:06-05:00</created-at>
      <elevation/>
      <last-entry-id type="integer">6062720</last-entry-id>
      <ranking type="integer">100</ranking>
      <username>hans</username>
      <tags type="array">
        <tag>
          <id type="integer">9</id>
          <name>temp</name>
        </tag>
        <tag>
          <id type="integer">25</id>
          <name>light</name>
        </tag>
      </tags>
    </channel>
    <channel>
      <id type="integer">5683</id>
      <name>Residential Data Points</name>
      <description>Arduino Uno + Ethernet Shield</description>
      <latitude type="decimal">35.664548</latitude>
      <longitude type="decimal">-78.654972</longitude>
      <created-at type="dateTime">2013-05-15T12:33:57-04:00</created-at>
      <elevation>100</elevation>
      <last-entry-id type="integer">731720</last-entry-id>
      <ranking type="integer">100</ranking>
      <username>samlro</username>
      <tags type="array">
        <tag>
          <id type="integer">950</id>
          <name>Analog Inputs</name>
        </tag>
      </tags>
    </channel>
  </channels>
</response>
Response in: TEXTJSONXML

List My Channels


To view a list of your Channels, send an HTTP GET to
https://127.0.0.1:3000/channels.json.xml .

Valid parameters:
  • api_key (string) - Your Account API Key (this is different from a Channel API Key, and can be found in your Account settings). (required)

Example GET:
GET https://127.0.0.1:3000/channels.json.xml

The response will be a webpage with a list of your Channels.
The response will be a JSON object of your Channels, for example:
[
  {
    "id": 9,
    "name": "my_house",
    "description": "Netduino Plus connected to sensors around the house",
    "latitude": "40.44",
    "longitude": "-79.996",
    "created_at": "2010-12-13T20:20:06-05:00",
    "elevation": "",
    "last_entry_id": 6062691,
    "ranking" :100,
    "username":"hans",
    "tags": [],
    "api_keys":
    [
      {
        "api_key": "XXXXXXXXXXXXXXXX",
        "write_flag": true
      }
    ]
  },
  {
    "id": 5683,
    "name": "Residential Data Points",
    "description": "Connected Arduino",
    "latitude": "32.664548",
    "longitude": "-73.654972",
    "created_at": "2013-05-15T12:33:57-04:00",
    "elevation": "100",
    "last_entry_id": 731713,
    "ranking": 100,
    "username": "hans",
    "tags": [],
    "api_keys":
    [
      {
        "api_key": "XXXXXXXXXXXXXXXX",
        "write_flag": true
      }
    ]
  }
]
The response will be an XML object of your Channels, for example:
<?xml version="1.0" encoding="UTF-8"?>
<channels type="array">
  <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.996</longitude>
    <created-at type="dateTime">2010-12-13T20:20:06-05:00</created-at>
    <elevation/>
    <last-entry-id type="integer">6062720</last-entry-id>
    <ranking type="integer">100</ranking>
    <username>hans</username>
    <tags type="array" />
    <api-keys type="array">
        <api-key>
            <api-key>XXXXXXXXXXXXXXXX</api-key>
            <write-flag type="boolean">true</write-flag>
        </api-key>
    </api-keys>
  </channel>
  <channel>
    <id type="integer">5683</id>
    <name>Residential Data Points</name>
    <description>Connected Arduino</description>
    <latitude type="decimal">32.664548</latitude>
    <longitude type="decimal">-73.654972</longitude>
    <created-at type="dateTime">2013-05-15T12:33:57-04:00</created-at>
    <elevation>100</elevation>
    <last-entry-id type="integer">731720</last-entry-id>
    <ranking type="integer">100</ranking>
    <username>hans</username>
    <tags type="array" />
    <api-keys type="array">
        <api-key>
            <api-key>XXXXXXXXXXXXXXXX</api-key>
            <write-flag type="boolean">true</write-flag>
        </api-key>
    </api-keys>
  </channel>
</channels>

Response in: TEXTJSONXML

View a Channel


To view a specific Channel, send an HTTP GET to
https://127.0.0.1:3000/channels/CHANNEL_ID.json.xml .

Valid parameters:
  • api_key (string) - User's API Key; please note that this is different than a Channel API key, and can be found in your account details. If this key is provided, the Channel's private details (such as the Channel's API keys) will also be shown. (optional).

Example GET:
GET https://127.0.0.1:3000/channels/1417.json.xml

The response will be a webpage that shows the Channel.
The response will be a JSON object of the Channel, for example:
{
  "id": 4,
  "name": "My New Channel",
  "description": null,
  "metadata": null,
  "latitude": null,
  "longitude": null,
  "created_at": "2014-03-25T13:12:50-04:00",
  "elevation": null,
  "last_entry_id": null,
  "ranking": 15,
  "username": "hans",
  "tags": []
}
The response will be an XML object of public Channels, for example:
<?xml version="1.0" encoding="UTF-8"?>
<channel>
    <id type="integer">4</id>
    <name>My New Channel</name>
    <description nil="true" />
    <metadata nil="true" />
    <latitude type="decimal" nil="true" />
    <longitude type="decimal" nil="true" />
    <created-at type="dateTime">2014-03-25T20:17:44-04:00</created-at>
    <elevation nil="true" />
    <last-entry-id type="integer" nil="true" />
    <ranking type="integer">15</ranking>
    <username>hans</username>
    <tags type="array" />
</channel>

Response in: TEXTJSONXML

Create a Channel


To create a new Channel, send an HTTP POST to https://127.0.0.1:3000/channels.json.xml .

Valid parameters:
  • api_key (string) - User's API Key; please note that this is different than a Channel API key, and can be found in your account details. (required).
  • description (string) - Description of the Channel (optional)
  • elevation (integer) - Elevation in meters (optional)
  • field1 (string) - Field1 name (optional)
  • field2 (string) - Field2 name (optional)
  • field3 (string) - Field3 name (optional)
  • field4 (string) - Field4 name (optional)
  • field5 (string) - Field5 name (optional)
  • field6 (string) - Field6 name (optional)
  • field7 (string) - Field7 name (optional)
  • field8 (string) - Field8 name (optional)
  • latitude (decimal) - Latitude in degrees (optional)
  • longitude (decimal) - Longitude in degrees (optional)
  • metadata (text) - Metadata for the Channel, which can include JSON, XML, or any other data (optional)
  • name (string) - Name of the Channel (optional)
  • public_flag (true/false) - Whether the Channel should be public, default false (optional)
  • tags (string) - Comma-separated list of tags (optional)
  • url (string) - Webpage URL for the Channel (optional)

Example POST:
POST https://127.0.0.1:3000/channels.json.xml
     api_key=XXXXXXXXXXXXXXXX
     name=My New Channel

The response will be a webpage with your newly created Channel.
The response will be a JSON object of the new channel, for example:
{
  "id": 4,
  "name": "My New Channel",
  "description": null,
  "metadata": null,
  "latitude": null,
  "longitude": null,
  "created_at": "2014-03-25T13:12:50-04:00",
  "elevation": null,
  "last_entry_id": null,
  "ranking": 15,
  "username": "hans",
  "tags": [],
  "api_keys":
  [
    {
      "api_key": "XXXXXXXXXXXXXXXX",
      "write_flag": true
    }
  ]
}
The response will be an XML object of the new channel, for example:
<?xml version="1.0" encoding="UTF-8"?>
<channel>
    <id type="integer">4</id>
    <name>My New Channel</name>
    <description nil="true" />
    <metadata nil="true" />
    <latitude type="decimal" nil="true" />
    <longitude type="decimal" nil="true" />
    <created-at type="dateTime">2014-03-25T20:17:44-04:00</created-at>
    <elevation nil="true" />
    <last-entry-id type="integer" nil="true" />
    <ranking type="integer">15</ranking>
    <username>hans</username>
    <tags type="array" />
    <api-keys type="array">
        <api-key>
            <api-key>XXXXXXXXXXXXXXXX</api-key>
            <write-flag type="boolean">true</write-flag>
        </api-key>
    </api-keys>
</channel>

Response in: TEXTJSONXML

Update a Channel


To update a Channel, send an HTTP PUT to
https://127.0.0.1:3000/channels/CHANNEL_ID.json.xml .

Valid parameters:
  • api_key (string) - User's API Key; please note that this is different than a Channel API key, and can be found in your account details. (required).
  • description (string) - Description of the Channel (optional)
  • elevation (integer) - Elevation in meters (optional)
  • field1 (string) - Field1 name (optional)
  • field2 (string) - Field2 name (optional)
  • field3 (string) - Field3 name (optional)
  • field4 (string) - Field4 name (optional)
  • field5 (string) - Field5 name (optional)
  • field6 (string) - Field6 name (optional)
  • field7 (string) - Field7 name (optional)
  • field8 (string) - Field8 name (optional)
  • latitude (decimal) - Latitude in degrees (optional)
  • longitude (decimal) - Longitude in degrees (optional)
  • metadata (text) - Metadata for the Channel, which can include JSON, XML, or any other data (optional)
  • name (string) - Name of the Channel (optional)
  • public_flag (true/false) - Whether the Channel should be public, default false (optional)
  • tags (string) - Comma-separated list of tags (optional)
  • url (string) - Webpage URL for the Channel (optional)

Example PUT:
PUT https://127.0.0.1:3000/channels/4.json.xml
    api_key=XXXXXXXXXXXXXXXX
    name=Updated Channel

The response will be a webpage with your updated Channel.
The response will be a JSON object of the updated channel, for example:
{
  "id": 4,
  "name": "Updated Channel",
  "description": null,
  "metadata": null,
  "latitude": null,
  "longitude": null,
  "created_at": "2014-03-25T13:12:50-04:00",
  "elevation": null,
  "last_entry_id": null,
  "ranking": 15,
  "username": "hans",
  "tags": [],
  "api_keys":
  [
    {
      "api_key": "XXXXXXXXXXXXXXXX",
      "write_flag": true
    }
  ]
}
The response will be an XML object of the updated channel, for example:
<?xml version="1.0" encoding="UTF-8"?>
<channel>
    <id type="integer">4</id>
    <name>Updated Channel</name>
    <description nil="true" />
    <metadata nil="true" />
    <latitude type="decimal" nil="true" />
    <longitude type="decimal" nil="true" />
    <created-at type="dateTime">2014-03-25T20:17:44-04:00</created-at>
    <elevation nil="true" />
    <last-entry-id type="integer" nil="true" />
    <ranking type="integer">15</ranking>
    <username>hans</username>
    <tags type="array" />
    <api-keys type="array">
        <api-key>
            <api-key>XXXXXXXXXXXXXXXX</api-key>
            <write-flag type="boolean">true</write-flag>
        </api-key>
    </api-keys>
</channel>

Response in: TEXTJSONXML

Clear a Channel


To clear all feed data from a Channel, send an HTTP DELETE to https://127.0.0.1:3000/channels/CHANNEL_ID/feeds.json.xml .

Valid parameters:
  • api_key (string) - User's API Key; please note that this is different than a Channel API key, and can be found in your account details. (required).

Example DELETE:
DELETE https://127.0.0.1:3000/channels/4/feeds.json.xml
       api_key=XXXXXXXXXXXXXXXX

The response will be a webpage with your Channel.
The response will be an empty JSON array, for example:
[]
The response will be an empty XML array, for example:
<?xml version="1.0" encoding="UTF-8"?>
<nil-classes type="array" />

Response in: TEXTJSONXML

Delete a Channel


To create a new Channel, send an HTTP DELETE to https://127.0.0.1:3000/channels/CHANNEL_ID.json.xml , replacing CHANNEL_ID with the ID of your Channel.

Valid parameters:
  • api_key (string) - User's API Key; please note that this is different than a Channel API key, and can be found in your account details. (required).

Example DELETE:
DELETE https://127.0.0.1:3000/channels/4.json.xml
       api_key=XXXXXXXXXXXXXXXX

The response will be a webpage with a list of Channels.
The response will be a JSON object of the Channel before it was deleted, for example:
{
  "id": 4,
  "name": "My New Channel",
  "description": null,
  "latitude": null,
  "longitude": null,
  "created_at": "2014-03-25T13:12:50-04:00",
  "elevation": null,
  "last_entry_id": null,
  "ranking": 15,
  "username": "hans",
  "tags": []
}
The response will be an XML object of the Channel before it was deleted, for example:
<?xml version="1.0" encoding="UTF-8"?>
<channel>
    <id type="integer">4</id>
    <name>My New Channel</name>
    <description nil="true" />
    <latitude type="decimal" nil="true" />
    <longitude type="decimal" nil="true" />
    <created-at type="dateTime">2014-03-25T20:17:44-04:00</created-at>
    <elevation nil="true" />
    <last-entry-id type="integer" nil="true" />
    <ranking type="integer">15</ranking>
    <username>hans</username>
    <tags type="array" />
</channel>



Importer

Using the ThingSpeak Importer, you are able to import data from a CSV file directly into a ThingSpeak Channel. The access the Importer, select a Channel, and click Import Data.

The format for the CSV should be the following:

datetime,field1,field2,field3,field4,field5,field6,field7,field8,latitude,longitude,elevation,status

Here is an example CSV file: Sample CSV File

You only have to send a datetime stamp and at least one field. The datetime stamp can be in many formats such as epoch, ISO 8601, or MySQL time. If the datetime includes a GMT/UTC offset, we will use that to properly import the data. If your datetime stamps do not have a GMT / UTC offset, you can specify a time zone that the data was logged in.