Selection Object

The selection object defines the resources and information to return as part of a response. The selection is required in all requests however meaning of some selection fields is only meaningful to certain types of requests.

The selectionType parameter defines the type of selection to perform. The selectionMatch specifies the matching criteria for the type specified.

Utility Restrictions

Utilities are constrained by a restricted list of GET (or view) access to certain include* properties of the Thermostat object. This exists to protect the Thermostat owner's private information.

The list of include* properties the Utility can use for GET requests is:

  • includeRuntime
  • includeExtendedRuntime
  • includeElectricity
  • includeSettings
  • includeLocation
  • includeProgram
  • includeEvents
  • includeDevice
  • includeTechnician
  • includeUtility
  • includeAlerts
  • includeWeather
  • includeOemConfig
  • includeEquipmentStatus
  • includeNotificationSettings
  • includePrivacy
  • includeVersion
  • includeSecuritySettings
  • includeSensors

Selection Type Account Type Selection Match Example Description
registered Smart only. match is not used. When this is set the thermostats registered to the current user will be returned. This is only usable with Smart thermostats registered to a user. It does not work on EMS thermostats and may not be used by a Utility who is not the owner of thermostats.
thermostats All accounts identifier1,identifier2,etc.. Select only those thermostats listed in the CSV match criteria. No spaces in the CSV string. There is a limit of 25 identifiers per request.
managementSet EMS/Utility only. /Toronto/Campus/BuildingA Selects all thermostats for a given management set defined by the Management/Utility account. This is only available to Management/Utility accounts. "/" is the root, represented by the "My Sets" set.

Properties

Name Type Read Only Required Description
selectionType Enum no yes The type of match data supplied: Values: thermostats, registered, managementSet.
selectionMatch String no yes The match data based on selectionType (e.g. a list of thermostat idendifiers in the case of a selectionType of thermostats)
includeRuntime boolean no no Include the thermostat runtime object. If not specified, defaults to false.
includeExtendedRuntime boolean no no Include the extended thermostat runtime object. If not specified, defaults to false.
includeElectricity boolean no no Include the electricity readings object. If not specified, defaults to false.
includeSettings boolean no no Include the thermostat settings object. If not specified, defaults to false.
includeLocation boolean no no Include the thermostat location object. If not specified, defaults to false.
includeProgram boolean no no Include the thermostat program object. If not specified, defaults to false.
includeEvents boolean no no Include the thermostat calendar events objects. If not specified, defaults to false.
includeDevice boolean no no Include the thermostat device configuration objects. If not specified, defaults to false.
includeTechnician boolean no no Include the thermostat technician object. If not specified, defaults to false.
includeUtility boolean no no Include the thermostat utility company object. If not specified, defaults to false.
includeManagement boolean no no Include the thermostat management company object. If not specified, defaults to false.
includeAlerts boolean no no Include the thermostat's unacknowledged alert objects. If not specified, defaults to false.
includeReminders boolean no no
includeWeather boolean no no Include the current thermostat weather forecast object. If not specified, defaults to false.
includeHouseDetails boolean no no Include the current thermostat house details object. If not specified, defaults to false.
includeOemCfg boolean no no Include the current thermostat OemCfg object. If not specified, defaults to false.
includeEquipmentStatus boolean no no Include the current thermostat equipment status information. If not specified, defaults to false.
includeNotificationSettings boolean no no Include the current thermostat alert and reminders settings. If not specified, defaults to false.
includePrivacy boolean no no Include the current thermostat privacy settings. Note: access to this object is restricted to callers with implict authentication, setting this value to true without proper credentials will result in an authentication exception.
includeVersion boolean no no Include the current firmware version the Thermostat is running. If not specified, defaults to false.
includeSecuritySettings boolean no no Include the current securitySettings object for the selected Thermostat(s). If not specified, defaults to false.
includeSensors boolean no no Include the list of current thermostatRemoteSensor objects for the selected Thermostat(s). If not specified, defaults to false.
includeAudio boolean no no Include the audio configuration for the selected Thermostat(s). If not specified, defaults to false.
includeEnergy boolean no no Include the energy configuration for the selected Thermostat(s). If not specified, defaults to false.

Back To Top