thingSpeakRead

Read data stored in ThingSpeak channel

Syntax

data = thingSpeakRead(channelID)

data = thingSpeakRead(channelID,Name=Value)

data = thingSpeakRead(___,ReadKey='channel Read API key')

[data,timestamps] = thingSpeakRead(___)

[data,timestamps,channelInfo] = thingSpeakRead(___)

Description

data = thingSpeakRead(channelID) reads the most recent data from all fields of the specified public channel on ThingSpeak.com and returns the data as a numeric type.

data = thingSpeakRead(channelID,Name=Value) uses additional options specified by one or more Name=Value pair arguments. To read nonnumeric data, you must specify the 'OutputFormat'.

data = thingSpeakRead(___,ReadKey='channel Read API key') uses the ThingSpeak™ Read API key to read from a private channel.

[data,timestamps] = thingSpeakRead(___) also returns timestamps from the specified channel on ThingSpeak.com and can include any of the input arguments in previous syntaxes.

[data,timestamps,channelInfo] = thingSpeakRead(___) also returns channel information.

Examples

Retrieve Three Points of Data from a Channel into a Timetable

Read the last three points of data from fields 1 and 4 of a public channel, and return the data into a timetable.

data = thingSpeakRead(12397,'Fields',[1,4],NumPoints=3,OutputFormat='TimeTable')

data =

  3×2 timetable

         Timestamps         WindDirectionNorth0Degrees    TemperatureF
    ____________________    __________________________    ____________
    18-Nov-2021 13:42:57                34                    70.4    
    18-Nov-2021 13:43:57                50                    70.4    
    18-Nov-2021 13:44:57                54                    70.6

Retrieve Five Minutes of Data from a Channel into a Timetable

Read the last five minutes of data from fields 1 and 4 of a public channel, and return the data into a table.

data = thingSpeakRead(12397,Fields=[1,4],NumMinutes=5,OutputFormat='TimeTable')

data =

  11×2 timetable

         Timestamps         WindDirectionNorth0Degrees    TemperatureF
    ____________________    __________________________    ____________

    18-Nov-2021 13:34:57                38                    70.6    
    18-Nov-2021 13:35:57                42                    70.6    
    18-Nov-2021 13:36:57                41                    70.6    
    18-Nov-2021 13:37:57                46                    70.8    
    18-Nov-2021 13:38:57                44                    70.8    
    18-Nov-2021 13:39:57                37                    70.8    
    18-Nov-2021 13:40:57                42                    70.6    
    18-Nov-2021 13:41:57                43                    70.4    
    18-Nov-2021 13:42:57                34                    70.4    
    18-Nov-2021 13:43:57                50                    70.4    
    18-Nov-2021 13:44:57                54                    70.6    
    18-Nov-2021 13:45:57                52                    70.

Retrieve Recent Data with Its Timestamp

Read the most recent result for all fields of a public channel, including the timestamp.

[data,timestamps] = thingSpeakRead(12397)

data =
   52.0000    7.6000   58.0000   70.8000         0   29.6700    4.1360         0


timestamps = 

  datetime

   18-Nov-2021 13:45:57

Retrieve Five Minutes of Data with Timestamps and Channel Information

Read the last five minutes of data from fields 1 and 4 of a public channel, including the timestamps and channel information.

[data,timestamps,channelInfo] = thingSpeakRead(12397,Fields=[1,4],NumMinutes=5)

data =

   41.0000   70.6000
   46.0000   70.8000
   44.0000   70.8000
   37.0000   70.8000
   42.0000   70.6000
   43.0000   70.4000
   34.0000   70.4000
   50.0000   70.4000
   54.0000   70.6000
   52.0000   70.8000
   39.0000   71.0000


timestamps = 

  11×1 datetime array

   18-Nov-2021 13:36:57
   18-Nov-2021 13:37:57
   18-Nov-2021 13:38:57
   18-Nov-2021 13:39:57
   18-Nov-2021 13:40:57
   18-Nov-2021 13:41:57
   18-Nov-2021 13:42:57
   18-Nov-2021 13:43:57
   18-Nov-2021 13:44:57
   18-Nov-2021 13:45:57
   18-Nov-2021 13:46:57


channelInfo = 

  struct with fields:

            ChannelID: 12397
                 Name: 'WeatherStation'
          Description: 'MathWorks Weather Station, West Garage, Natick, MA 01760, USA'
             Latitude: 42.2997
            Longitude: -71.3505
             Altitude: 60
              Created: 20-May-2014 17:50:32
              Updated: 18-Nov-2021 13:40:31
          LastEntryID: 3638608
    FieldDescriptions: {1×8 cell}
             FieldIDs: [1 2 3 4 5 6 7 8]
                  URL: 'https://api.thingspeak.com/channels/12397/feed.json?'

Retrieve Data from a Specific Date Range

Read the data from 11:59:01 on August 9, 2018 through 12:02:52 on August 10, 2018 for fields 1 and 4 of a public channel, including the timestamps and channel information.

[data,timestamps,channelInfo] = thingSpeakRead(12397,Fields=[1 4],...
    DateRange=[datetime(2018,8,9,23,59,01),datetime(2018,8,10,0,02,52)])

data =

  202.0000   83.3000
  184.0000   83.2000
  185.0000   83.1000
  155.0000   83.1000


timestamps = 

  4×1 datetime array

   09-Aug-2018 23:59:17
   10-Aug-2018 00:00:20
   10-Aug-2018 00:01:21
   10-Aug-2018 00:02:22


channelInfo = 

  struct with fields:

            ChannelID: 12397
                 Name: 'WeatherStation'
          Description: 'MathWorks Weather Station, West Garage, Natick, MA 01760, USA'
             Latitude: 42.2997
            Longitude: -71.3505
             Altitude: 60
              Created: 20-May-2014 17:50:32
              Updated: 14-May-2020 10:31:40
          LastEntryID: 2853000
    FieldDescriptions: {'Wind Direction (North = 0 degrees)'  'Wind Speed (mph)'  '% Humidity'  'Temperature (F)'  'Rain (Inches/minute)'  'Pressure ("Hg)'  'Power Level (V)'  'Light Intensity'}
             FieldIDs: [1 2 3 4 5 6 7 8]
                  URL: 'https://api.thingspeak.com/channels/12397/feed.json?'

Input Arguments

channelID — Channel identification number

numeric

The channel identification number, specified as a positive integer. For private channels, you must also specify the ReadKey argument.

Data Types: double

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: thingSpeakRead(12397,Location=true); thingSpeakRead(12397,'Location',true);

DateRange — Range of time for collected data

datetime vector

Range of time for collected data to return, specified as a name-value pair consisting of 'DateRange' and an array of values that have [startdate,enddate] in MATLAB^® datetime (MATLAB) values. ThingSpeak server limits the number of points returned to a maximum of 8000. Adjust your ranges or make multiple calls if you need more than 8000 points of data.

Note

You cannot use DateRange with NumDays or NumMinutes.

Example: thingSpeakRead(12397,DateRange=[datetime('Aug 8, 2014'),datetime('Aug 12, 2014')]);

Fields — Channel fields

positive numeric scalar

Channel field IDs, specified as a name-value pair consisting of Fields and numeric values of the channel field ID to retrieve data from.

Example: thingSpeakRead(12397,Fields=[1,3,4]);

Location — Positional information of data

logical

Indicator to display positional information of data from the channel, specified as a name-value pair consisting of Location and a logical value. Location information includes latitude, longitude, and altitude.

Example: thingSpeakRead(12397,Location=true);

NumDays — Number of days of data

positive numeric scalar

Number of days of data to extract data from, specified as a name-value pair consisting of 'NumDays' and a numeric value. Number of days is measured in 24-hour periods. The ThingSpeak server limits the number of points returned to a maximum of 8000. Adjust your number of days, or make multiple calls if you need more than 8000 points of data.

Note

You cannot use NumDays with DateRange or NumMinutes.

Example: thingSpeakRead(12397,NumDays=2);

NumMinutes — Number of minutes of data

positive numeric scalar

Number of minutes of data to extract data from, specified as a name-value pair consisting of 'NumMinutes' and a numeric value. Number of minutes of data to retrieve is measured from the time the command is issued. The ThingSpeak server limits the number of points returned to a maximum of 8000. Adjust your number of minutes, or make multiple calls if you need more than 8000 points of data.

Note

You cannot use NumMinutes with DateRange or NumDays.

Example: thingSpeakRead(12397,NumMinutes=20);

Data Types: double

NumPoints — Number of data points

positive numeric scalar

Number of data points to extract, specified as a name-value pair consisting of 'NumPoints' and a numeric value. The number of points or rows of data is counted from the time the command is issued. The ThingSpeak server limits the number of points returned to a maximum of 8000.

Example: thingSpeakRead(12397,NumPoints=200);

OutputFormat — Class of the output data

matrix (default) | table | timetable

Class of the output data, specified as a comma-separated pair consisting of 'OutputFormat' and a text value. Valid values are 'matrix', 'table', and 'timetable'. Use 'matrix' format for numeric data. You can use 'timetable' or 'table' for any nonnumeric data. The 'table' format outputs [data,channelInfo], where data contains the timestamps and the data from the fields of the channel. The 'timetable' format outputs [data,channelInfo], where data is a timetable and contains as many variables as the number of requested 'fields'.

Example: thingSpeakRead(12397,OutputFormat='table');

Example: thingSpeakRead(12397,OutputFormat='timetable');

ReadKey — Read API key of channel

character vector of API Key | string scalar of API Key

Read API key of the channel, specified as a name-value pair consisting of 'ReadKey' and a character vector representing a channel read API key. The Read API key allows you to read data from a private channel. You can find the Read API key for a channel on the API Keys tab of your ThingSpeak channel view. If you are reading data from a public channel, you do not need a Read API key. Save your channel Read API key in a variable for convenience.

Example: thingSpeakRead(12397,ReadKey='F6CSCVKX42WFZN9Y');

Data Types: char

Timeout — Server connection timeout period

10 (default) | positive numeric scalar

Server connection timeout period, specified as a name-value pair consisting of 'Timeout' and a numeric value. The value is the number of seconds allowed for thingSpeakRead to connect to the server.

Example: thingSpeakRead(12397,Timeout=15);

Output Arguments

data — Data from the channel

array (default) | table | timetable

Data from the channel, returned as an array, table, or timetable.

timestamps — Timestamp of each data element

array (default)

Timestamp of each data element, returned as an array of datetime values.

Data Types: datetime

channelInfo — Channel information

structure

Channel information, returned as a structure with fields in the order shown in the table..

Field	Description
ChannelID	Channel identification number
Name	Name of the channel
Description	Channel description
Latitude	Latitude for the channel as provided in the channel settings
Longitude	Longitude for the channel as provided in the channel settings
Altitude	Elevation for the channel as provided in the channel settings
Created	Datetime of channel creation date
Updated	Datetime when the channels settings were last changed
Last EntryID	Entry ID for the most recent channel update
Field Descriptions	List of field names
Field IDs	List of enabled fields
URL	URL for feed data

More About

ThingSpeak

ThingSpeak is an IoT analytics platform service that allows you to aggregate, visualize, and analyze live data streams in the cloud. See License Options and the Commercial Use for more information.

Version History

Introduced in R2019a