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

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.

If the endpoint returns one of the values of these pairs: 0/1, "0"/"1", FALSE/TRUE, false/true, off/on or closed/open it can be used as-is. If the return value differs, 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 %}

{% include integrations/using_templates.md %}

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