home-assistant.io/source/_components/sensor.rest.markdown

layout, title, description, date, sidebar, comments, sharing, footer, ha_category, ha_release

layout	title	description	date	sidebar	comments	sharing	footer	ha_category	ha_release
page	RESTful Sensor	Instructions how to integrate REST sensors into Home Assistant.	2015-09-14 19:10	true	false	true	true	Sensor	0.7.4

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

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

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

or for a POST request:

# Example configuration.yaml entry
sensor:
  platform: rest
  resource: http://IP_ADDRESS/ENDPOINT
  method: POST
  payload: '{ "device" : "heater" }'

Configuration variables:

• resource (Required): The resource or endpoint that contains the value.
• method (Optional): The method of the request. Default is GET.
• value_template (Optional): Defines a template to extract the value.
• payload (Optional): The payload to send with a POST request. Depends on the service, but usually formed as JSON.
• name (Optional): Name of the REST sensor.
• unit_of_measurement (Optional): Defines the unit of measurement of the sensor, if any.
• verify_ssl (Optional): Verify the certification of the endpoint. Default to True.
• authentication (Optional): Type of the HTTP authentication. basic or digest.
• username (Optional): The username for accessing the REST endpoint.
• password (Optional): The password for accessing the REST endpoint.
• headers (Optional): The headers for the requests.

Make sure that the URL matches exactly your endpoint or resource.

curl could help you with the identification of the variable you want to display in your Home Assistant frontend. The example below show the JSON response of a device that is running with aREST.

$ curl -X GET http://192.168.1.31/temperature/
{"temperature": 77, "id": "sensor02", "name": "livingroom", "connected": true}

{% linkable_title Examples %}

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

{% linkable_title External IP address %}

You can find your external IP address using the service JSON Test at their http://ip.jsontest.com/ endpoint.

To display the IP address, the entry for a sensor in the configuration.yaml file will look like this.

  - platform: rest
    resource: http://ip.jsontest.com
    name: External IP
    value_template: '{% raw %}{{ value_json.ip }}{% endraw %}'

{% linkable_title Single value from a local Glances instance %}

The glances sensor is doing the exact same thing for all exposed values.

Add something similar to the entry below to your configuration.yaml file:

  - platform: rest
    resource: http://IP_ADRRESS:61208/api/2/mem/used
    name: Used mem
    value_template: '{% raw %}{{ value_json.used| multiply(0.000000954) | round(0) }}{% endraw %}'
    unit_of_measurement: MB

{% linkable_title Value for other Home Assistant instance %}

The Home Assistant API exposes the data from your attached sensors. If you are running multiple Home Assistant instances which are not connected you can still get information from them.

  - platform: rest
    resource: http://IP_ADDRESS:8123/api/states/sensor.weather_temperature
    name: Temperature
    value_template: {% raw %}'{{ value_json.state }}'{% endraw %}
    unit_of_measurement: "°C"

{% linkable_title Accessing a HTTP authentication protected endpoint %}

The REST sensor supports HTTP authentication and customized headers.

  - platform: rest
    resource: http://IP_ADDRESS:5000/sensor
    username: ha1
    password: test1
    authetication: basic
    headers:
      User-agent: Home Assistant
      Content-Type: application/json

The header will contains all relevant details. This will give you the flexibility to access also endpoints wich are protected by Tokens.

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