Round Thermostat Getting Started Guide

What Can I Do With the Honeywell Home Thermostat API?

You can control the various functions of our Honeywell Home Round Thermostat as well as get status from the device itself including:

• Getting and changing current setpoint(s)

• Getting and changing System Mode (e.g., Heat, Cool, Off)

• Get and change the Fan Mode

• Get current indoor temperature and indoor humidity readings

• Get user and location information

Note: A physical Honeywell Home device is required to use the API. We currently do not have a simulator.

To start using the API you have two options:

• Using the interactive documentation which gets you past the step of setting up an OAuth redirect URL for tokens
• Registering an OAuth Redirect URL to your application and using your own code

Requirements:

• A Honeywell Home account with a connected/installed device
• An API Key

Example API Call Flow:

First: Make sure you have an OAuth token or are using the built in documentation. If you aren't familiar with OAuth, start with the OAuth2 Guide.

Second: Get a user's locations and devices. Here you'll want to store the locationIDs and deviceIDs for later use in changing settings.

Request:

curl -H "Authorization: Bearer accessTokenHere" api.honeywellhome.com/v2/locations?apikey=yourApiKeyHere

Response Snippet:

[
  {
    "locationID": 29769,
    "name": "home",
    "streetAddress": "1985 Douglas drive",
    "city": "Golden valley",
    "state": "MN",
    "country": "Usa",
    "zipcode": "55422",
    "devices": [
      {
        "deviceID": "TCC-1105359",
        "name": "Desk Test",
        "userDefinedDeviceName": "Desk Test"....

Third: You can use the locationId to get all the devices for a particular location

Request:

curl -H "Authorization: Bearer accessTokenHere" api.honeywell.com/v2/devices?apikey=apiKeyHere&locationId=29769

Response Snippet:

[
  {
    "deviceID": "TCC-1105359",
    "name": "Desk Test",
    "userDefinedDeviceName": "Desk Test",
    "thermostat": {
      "units": "Fahrenheit",
      "indoorTemperature": 73.0000,
      "outdoorTemperature": 57.0000,
      "allowedModes": [
        "Cool",
        "Heat",
        "Off"
      ],
      "deadband": 0.0000,
      "hasDualSetpointStatus": false,
      "minHeatSetpoint": 40.0000,
      "maxHeatSetpoint": 90.0000,
      "minCoolSetpoint": 50.0000,
      "maxCoolSetpoint": 99.0000,
      "changeableValues": {
        "mode": "Heat",
        "autoChangeoverActive": true,
        "heatSetpoint": 73.0000,
        "coolSetpoint": 78.0000
      }....
]

Fourth: The part we are should focus on is the "changeableValues" array. I'm too cold, so I'd appreciate if you change the setpoint up a couple degrees. It is a best practice to just take the changeableValues array and modify the settings you wish to change and leave the rest as-is when you POST it back.

curl -X POST -H "Authorization: Bearer accessTokenHere" -H "Content-Type: application/json" -d '{ "mode": "Heat", "autoChangeoverActive": true, "heatSetpoint": 74,"coolSetpoint": 78 }' https://api.honeywell.com/v2/devices/thermostats/TCC-1105359?apikey=apiKeyHere&locationId=29769

You should recieve a 200 response, and the setpoint on your device should change pretty quickly after that.