Rest sensors are sensors that read data from an API of a web application. It may be a bit confusing if it is not something you have worked with before but rest assured, it starts to click once you have done it a few times.

What is an API?

An API is an “Application Programming Interface” and what that basically means, is that it is a way to get information from a web application. The simple explanation of how it works, is that you can go to a specific web URL, and what comes up is information that you requested in an easy-to-digest format. The format could be a variety of programming languages, but many of them will use the JSON format. The example I will use below will use JSON as the programming language.

Deciding on an API

It will take time to decide what kinds of information you want to pull in to your smart home. Especially when that information is coming from a website and not a sensor in your own home. Sometimes you will realize a part of your daily routine involves relying on traffic information, or maybe a bus or train schedule. As you explore, you will find that many of these services offer an API that you can interact with and in turn, bring in to your smart home.

I happen to live near a lake that has an API for the current water level. This information may not be important in many situations, but I do like to have the information to keep track of it using restful sensors. It can be found on the USGS Water Services website.

Finding the API

In order to find the data we are looking for, we need to figure out how the service offers the information. For the USGS Water Services website, we are looking for information on the lake near my house. This process is not the easiest, but it only needs to be done one time.

First, we need to find out what county the lake is in for us to retrieve it’s information. Using the NWIS mapper tool, you can find the sites from which you want your data. Once you have found your site, you can click on it to find out what information is available on that site. Clicking on the “Current Data” link will get you to the page that has the specific site information.

After clicking on the Daily Data link, we will see the list of “Available Parameters” which has the USGS code numbers for the data we want. Keep note of these USGS code numbers, as well as the USGS site number for the dataset that you clicked. We will need those to build the URL for our RESTful sensor to access.

For the “Required Arguments” we will check the “Site or Sites” box and then we will input the USGS site that we selected from the previous step.

In the “Optional Arguments” field, we will select JSON as the “Output Format” and then scroll down to input the parameter codes that we decided on from the last step.

Now we can scroll down to the bottom of the page and press “Generate the URL” which will be the URL we will add to Home Assistant to get our RESTful Sensor. Once you’ve pressed that, you will press “Run the Generated URL” so that you can see the output of what we will be able to bring into our smart home.

Don’t be scared. The jumbled mess of words, letters, and symbols are the JSON that was created with your parameters. You can copy and paste this information into a JSON formatter that will make it much easier to read.

You will scroll through output until you find the data value or values that you are looking for. In my case, I am looking for the level of the lake. I have a general idea of the number I am looking for so it makes it simple. For this API specifically, each value is in it’s own timeSeries so that is a good way to try and find it.

Here I am looking for value “199.63” and I have collapsed everything above it to single out the path to getting to that number. The first step to getting there is the first “value”, followed by “timeSeries”, then there are two blank arrays and I am looking for the second one which will be [1] , then “values”, then the first array for that so a [0], then “value”, then the first array for that so another [0], then “value” again. That string all together looks like this: [‘value’][‘timeSeries’][1][‘values’][0][‘value’][0][‘value’]. This is what we need to bring this data point into our RESTful sensor on Home Assistant.

Adding RESTful Sensor to Home Assistant

We now have the URL to access our data and the path to that data in the JSON format. Next we simply at a rest sensor to our config.yaml file and it will start scanning every 60 seconds and updating that sensor for us.

sensor:
  - platform: rest
    resource: [INPUT THE FULL URL TO THE API HERE]
    value_template: "{{ value_json[INPUT THE FULL STRING FROM ABOVE HERE]
    unit_of_measurement: ft 

The resource is the API URL and the value_template is how it will find the data to bring in. Make sure that you are using JSON if you use the value_json value template. Adding a unit of measurement is optional but it makes charting your RESTful sensor more clean.

And that’s it! It seems like a lot but take it one step at a time and this is the same method you can use to add any API data as a RESTful sensor to your smart home.

TL;DR

1. Get API URL
2. Copy JSON response from API URL into JSON Formatter
3. Find Path to Data Point you want as RESTful Sensor
4. Add Sensor to config.yaml