home-assistant.io/source/_integrations/binary_sensor.rest.markdown

title, description, ha_category, ha_release, ha_iot_class, ha_domain

title	description	ha_category	ha_release	ha_iot_class	ha_domain
RESTful binary sensor	Instructions on how to integrate REST binary sensors into Home Assistant.	Binary sensor	0.10	Local Polling	rest

The rest binary sensor platform is consuming a given endpoint which is exposed by a RESTful API of a device, an application, or a web service. The binary sensor has support for GET and POST requests.

Tip: If you want to create multiple sensors using the same endpoint, use the RESTful configuration instructions.

The JSON messages can contain different values like 1, "1", TRUE, true, on, or open. If the value is nested then use a template. If the endpoint returns XML with the text/xml, application/xml, or application/xhtml+xml content type, it will automatically be converted to JSON according to this specification.

{
    "name": "Binary sensor",
    "state": {
        "open": "true",
        "timestamp": "2016-06-20 15:42:52.926733"
    }
}

Configuration

To enable this sensor, add the following lines to your {% term "configuration.yaml" %} file for a GET request:

# Example configuration.yaml entry
binary_sensor:
  - platform: rest
    resource: http://IP_ADDRESS/ENDPOINT

or for a POST request:

# Example configuration.yaml entry
binary_sensor:
  - platform: rest
    resource: http://IP_ADDRESS/ENDPOINT
    method: POST

or a template based request:

{% raw %}

# Example configuration.yaml entry
binary_sensor:
  - platform: rest
    resource_template: "http://IP_ADDRESS/{{ now().strftime('%Y-%m-%d') }}"

{% endraw %}

{% configuration %} resource: description: The resource or endpoint that contains the value. required: true type: string default: string resource_template: description: The resource or endpoint that contains the value with template support. required: false type: template method: description: The method of the request. required: false type: string default: GET name: description: Name of the REST binary sensor. required: false type: template default: REST Binary Sensor icon: description: Defines a template for the icon of the entity. required: false type: template picture: description: Defines a template for the entity picture of the entity. required: false type: template availability: description: Defines a template if the entity state is available or not. required: false type: template device_class: description: Sets the class of the device, changing the device state and icon that is displayed on the frontend. required: false type: string value_template: description: > Defines a template to extract the value. required: false type: template payload: description: The payload to send with a POST request. Usually formed as a dictionary. required: false type: string unique_id: description: An ID that uniquely identifies this entity. This allows changing the name, icon and entity_id from the web interface. required: false type: string verify_ssl: description: Verify the certification of the endpoint. required: false type: boolean default: true timeout: description: Defines max time to wait data from the endpoint. required: false type: integer default: 10 authentication: description: "Type of the HTTP authentication. basic or digest." required: false type: string username: description: The username for accessing the REST endpoint. required: false type: string password: description: The password for accessing the REST endpoint. required: false type: string headers: description: The headers for the requests. required: false type: [list, template] params: description: The query params for the requests. required: false type: [list, template] {% endconfiguration %}

Examples

In this section you find some real-life examples of how to use this sensor.

aREST sensor

Instead of using an aREST binary sensor, you could retrieve the value of a device supporting aREST directly with a REST binary sensor.

{% raw %}

binary_sensor:
  - platform: rest
    resource: http://192.168.0.5/digital/9
    method: GET
    name: Light
    device_class: light
    value_template: '{{ value_json.return_value }}'

{% endraw %}

Accessing an HTTP authentication protected endpoint

The REST sensor supports HTTP authentication and template-enabled customized headers.

{% raw %}

binary_sensor:
  - platform: rest
    resource: http://IP_ADDRESS:5000/binary_sensor
    username: ha1
    password: test1
    authentication: basic
    headers:
      User-Agent: Home Assistant
      Content-Type: application/json
      X-Custom-Header: '{{ states("input_text.the_custom_header") }}'

{% endraw %}

The headers will contain all relevant details. This will also give you the ability to access endpoints that are protected by tokens.

Content-Length: 1024
Host: IP_ADDRESS1:5000
Authorization: Basic aGExOnRlc3Qx
Accept-Encoding: identity
Content-Type: application/json
User-Agent: Home Assistant