Main Content

ThingHTTP App

ThingHTTP enables communication among devices, websites, and web services without having to implement the protocol on the device level. You specify actions in ThingHTTP, which you trigger using other ThingSpeak™ apps such as TimeControl and React.

Create a ThingHTTP Request

  1. Create a new ThingHTTP request. Click Apps > ThingHTTP, and then click New ThingHTTP.

  2. Specify settings. Not all settings are required for each type of request. The following parameters are required for all ThingHTTP requests.

    Required ParameterDescription
    NameEnter a unique name for your ThingHTTP request.
    API KeyAuto generated API key for the ThingHTTP request.
    URLEnter the address of the website or the web service that you are requesting data from, starting with https://. (Note that http:// is supported, but is strongly discouraged.)
    Method

    Select one of the following HTTP methods required to access the URL: GET, POST, PUT, or DELETE.

    HTTP VersionSpecify 1.1 unless directed otherwise by your server.

    Depending on the nature of the request you are making, you can specify additional parameters. For example, the username and password are needed for a ThingHTTP request to a server that requires authentication.

    Optional ParameterDescription
    HTTP Auth UsernameIf your URL requires authentication, enter the username for authentication to access private channels or websites.
    HTTP Auth PasswordIf your URL requires authentication, enter the password for authentication to access private channels or websites.
    Content TypeEnter the MIME or form type of the request content. For example, application/x-www-form-urlencoded.
    HostIf your ThingHTTP request requires a host address, enter the domain name. For example, api.thingspeak.com.
    HeadersIf your ThingHTTP request requires custom headers, enter name of the header and a value. For example, specify a byte range using Range: bytes=500-999.
    Body

    Enter a message you want to include in your request.


    You can also include data to send to the ThingHTTP app in the body section using replacement keys. For an example, see Pass Data with ThingHTTP Trigger.

    Parse String

    Enter a label to look for in the response data.
    You can use a unique ID or the XPATH to parse specific data from HTML. If the data returned is a JSON object, you can use JSON dot notation to parse the response data for a specific value. See Parse String for more information.

  3. Save the request. Your ThingHTTP is available for future use by clicking Apps and choosing ThingHTTP.

Trigger ThingHTTP

Trigger your ThingHTTP using a GET or POST HTTP request, TimeControl, or React. Use a POST request if you include data or use custom replacement keys. Requests triggered by POST, TimeControl, or React can pass certain variables to ThingHTTP. For more information, see Pass Data with ThingHTTP Trigger. For example, if you use TimeControl to trigger your ThingHTTP, you can pass the time it was triggered. This table provides input and output parameters and a sample call for using an HTTP request to trigger a ThingHTTP.

Note

Triggering ThingHTTP more than once per second results in an HTTP 429 status code. The status code continues until you reduce the rate below one request per second.

Trigger ThingHTTP with HTTP Request

TitleHTTP POST Request to Trigger ThingHTTP
URLhttps://api.thingspeak.com/apps/thinghttp/send_request
HTTP MethodPOST
HTTP Header Content-Type: application/x-www-form-urlencoded
X-THINGSPEAKAPIKEY = XXXXXXXXXXXXXXX
Data Parametersapi_key=XXXXXXXXXXXXXXX
Success Response200 OK
and HTTP, JSON, or text, depending on the ThingHTTP
Error Responses400 Invalid API key
0 Minimum wait time not reached
-1 Request failed
NotesYour ThingHTTP API key must appear in either the HTTP header or in the body section, or it can appear in both.
If you are not passing data to the ThingHTTP, you can use a GET request to trigger the ThingHTTP:
GET https://api.thingspeak.com/apps/thinghttp/send_request?api_key=XXXXXXXXXXXXXXX.

ThingHTTP returns the result of the HTTP request.

Pass Data with ThingHTTP Trigger

You can send data to ThingHTTP using replacement keys, including keys within two percent signs. You can include a replacement key in any available section of your ThingHTTP. For example, you can include a tag in the ThingHTTP body, and pass the data using the POST that triggers your ThingHTTP request. This example shows how to use a ThingHTTP request to post a message to a ThingSpeak Channel. Create your ThingHTTP, and use the custom replacement key %%message%% in the body.

When you include a message in a POST that triggers your ThingHTTP, the HTTP POST triggers your ThingHTTP, replaces %%message%% with ‘1234’ and updates the channel on ThingSpeak. The body parameters for your ThingHTTP are different from the body parameters for the HTTP trigger request. The HTTP trigger request parameters are shown in the following table.

TitleHTTP POST Request to Trigger ThingHTTP
URLhttps://api.thingspeak.com/apps/thinghttp/send_request
HTTP MethodPOST
HTTP Header Content-Type: application/x-www-form-urlencoded
X-THINGSPEAKAPIKEY=XXXXXXXXXXXXXXX
Data Parametersapi_key=XXXXXXXXXXXXXXX
message=1234
Success Response200 OK
and HTTP, JSON, or text, depending on your ThingHTTP
Error Responses400 Invalid API key
0 Minimum wait time not reached
-1 Request failed
NotesYour ThingHTTP API key must appear in either the HTTP header or the body section, or it can appear in both.

POSTMAN Request Using Replacement Key

You can use POSTMAN to try out your HTTP requests using the RESTful API for ThingSpeak. The following shows how to test your ThingHTTP with replacement keys using POSTMAN.

  1. Select POST and enter the request URL.

  2. Select Body in the authorization section.

  3. Choose x-www-form-urlencoded.

  4. Enter api_key and copy your ThingHTTP API key to the value section.

  5. Enter message and the message text in the value section.

Replacement Keys

You can pass data to your apps using replacement keys. The following table summarizes the standard and custom replacement keys you can use. Some keys are specific to a particular type of request, as indicated in the last column.

KeyDescriptionExampleUse With
%%YOUR_CUSTOM_LABEL%%ThingHTTP replaces this custom replacement value with data in the trigger request that has the label "YOUR_CUSTOM_LABEL".field1=%%YOUR_CUSTOM_LABEL%%
POST data: YOUR_CUSTOM_LABEL=1234.
RESULT: field1=1234.		Any request
%%channel_CHANNEL_ID_
field_FIELD_NUMBER%%		The last value of the specified channel and field. Replacement requests to private channels not owned by the same user as the ThingHTTP request return blank values.The latest value is %%channel_12_field_1%%.
RESULT: The latest value is 2.5.		Any request
%%datetime%%The full date and time when the TimeControl or React ran.The date and time the event occurred is %%datetime%%.
RESULT: The date and time the event occurred is 2014-09-24 5:32 p.m.		TimeControl or React
%%day%%The name of the weekday when TimeControl ran.The day the event occurred is %%day%%.
RESULT: The day the event occurred is Wednesday.		TimeControl
%%day_index%% The zero-based index of the weekday starting on Sunday.The number of days used this week is %%day_index%%.
RESULT: The number of days used this week is 3.		TimeControl
%%hour%%The hour of the day when TimeControl ran.The hour that the event occurred is %%hour%%.
RESULT: The hour that the event occurred is 5.		TimeControl
%%minute%%The minute of the hour when the TimeControl ran.The minute the event occurred is %%minute%%.
RESULT: The minute the event occurred is 30.		TimeControl
%%trigger%%The value that triggered React.It is way too hot in here at %%trigger%% C.
RESULT: It is way too hot in here at 40 C.		React
%%channel_id%%The channel ID that triggered React.The channel that triggers is %%channel_id%%.
RESULT: The channel that triggers is 1256.		React

Parse String

ThingHTTP sends the complete HTTP response generated by the request, which can be a web page, text, or JSON object. To extract a single data element from the response, specify Parse String in your ThingHTTP request. ThingHTTP can parse data using unique tag ID or XPATH data. JSON objects can be parsed to retrieve components of the object.

XPath

You can use XML Path Language (XPath) to specify a particular value on a web page. Specify the XPath of an item on a web page to parse for that specific item. Some browsers provide XPATH information when you click the data in the source view. For example, the web page www.localconditions.com/massachusetts/01750 provides the Moon phase for Natick, MA in the XPATH
//*[@id="wrapper"]/div[3]/div/div[2]/div[1]/div[1]/div/div[2]/div[2]/p[5]/text().

JSON

JSON (JavaScript Object Notation) is commonly used to format web data. If your request returns a JSON object, you can use the appropriate dot notation to retrieve the value of interest. ThingSpeak Channel 12397 provides weather information from the parking garage at MathWorks® in Natick. Using the request URL https://api.thingspeak.com/channels/12397/feeds.json?results=1 returns a JSON object, similar to the one shown here. Use the parse string feeds[0].field2 to retrieve the latest value of the Wind Speed, in this case the value returned is 5.0.

Here is a sample of the weather station JSON Object returned from the MathWorks ThingSpeak weather station channel.

{  "channel": {
    "id": 12397,
    "name": "WeatherStation",
    "description": "MathWorks Weather Station, ...",
    ...
    "field1": "Wind Direction ... ",
    "field2": "Wind Speed (mph)",
    ...  },
  "feeds": [
    {
      "created_at": "2017-03-13T14:33:21Z",
      "entry_id": 1272044,
      "field1": "21",
      "field2": "5.0",
     ...    }  ]}

See Also

Functions

External Websites