Outdoor illuminance estimated from weather conditions reported by Weather Underground


If you would like to create automations that depend on the outdoor light level but you don’t have a real light sensor, this custom sensor platform might be what you’re looking for. It periodically polls current weather conditions from Weather Underground and uses that, and the time of day, to provide an estimate. I’ve been using this algorithm for quite some time (first with SmartThings, and now with HA) and although it’s obviously not perfect, it (usually) does a pretty good job. :slight_smile:

E.g., here is a graph of the values it provided for the last few days for me. As you can see, yesterday was sunny all day, and the previous day there was some decreasing cloud cover. Also you will note the ramping up and down around sunrise and sunset, respectively. That is a feature of the algorithm.
To use this you will need a Weather Underground API Key. You can find details here for how to obtain a free one: https://www.wunderground.com/weather/api/d/pricing.html

NOTE: It appears that Weather Underground no longer provides free API keys. Existing ones, though, do still appear to work. (Mine does as of 5/25/2018.) I’m currently looking into using other sources of current weather conditions as an alternative to WU.

Add the following to your configuration.yaml file:

  - name: Illuminance
    platform: illuminance
    api_key: !secret wu_api_key
    query: 'pws:XXX'
      minutes: 5

name and scan_interval are optional. The default scan interval is 5 minutes.

api_key is required. This is the key you get from WU per the instructions mentioned above.

query is required. See https://www.wunderground.com/weather/api/d/docs?d=data/index for your options. In my case I use a local Personal Weather Station (pws).

I welcome any feedback. (E.g., if I completely missed the fact that this information is already available via some other, existing component, please let me know! :slight_smile:)

You can obtain the code from here:

Place it at this location: <config>/custom_components/sensor/illuminance.py, where <config> is your Home Assistant configuration directory.

Outdoor illuminance estimated by sunrise, sunsite and weather conditions
Quantifying the brightness outside

Thanks for this, I was looking for something similar just last week.


Nice, I’m using it now. Will let you know how it goes.

Might use it to control with my lights turn on and off with motion and their brightness. I have LUX sensors in most rooms but they’re not always quick enough to update, so this may help me! Thanks!


Update: Abort update (and log error) if current observation icon (which algorithm is based on) is empty or is an unexpected value. Previously this caused an illuminance value of zero.


According to the WU site, they no longer provide free API keys. Bumma


Whoa! That’s pretty new. They were still available when I created this topic post. Hmm, I wonder if that means previously provided keys will stop working at some point. :slightly_frowning_face:.


@pnbruckner Thanks for this, it looks great and just what I was looking for (assuming my WU api key doesn’t stop working!!).

Am I right in assuming that the conditions which cause an error are rare? The reason I’m asking is, if it is not rare then what action does your automation take on error conditions and how do you interrogate this situation? Of course if the error only happens infrequently then it is not an issue.

I have just added this to my setup for testing and will report back!


I definitely see errors from time to time. Either the request to WU times out, or sometimes it returns an error 401 or something. But in those cases my platform aborts the update and the entity’s value just won’t change for that poll cycle. Errors don’t seem to happen too often, but sometimes there might be a few in a row. Of course, weather conditions don’t change very fast either, so I’ve not seen this to be a problem.

Regarding the WU API key, yeah, that is a bummer that they’ve stopped offering new free keys. But so far (fingers crossed!) the existing ones seem to still work. I have thought, though, that this algorithm could be easily adapted to other sources of data. Basically it just requires a mapping of some weather condition to an estimated illuminance value. E.g., it could be adapted to the YR platform’s symbol sensor. One would just have to know something about what those numbers mean. I tried looking at the YR website, but the link I followed that I thought might provide some insights into that seems to only be available in Norwegian. :slight_smile:


Dark Sky provides some data that may be useful also. Since I couldn’t get a WU API, I got one from Dark Sky. The luminance data is pretty coarse (“cloudy” “clear” “drizzle” “rain”) but may be useful. I’m experimenting with some node red automations to allow lights to turn on on detecting motion but only if Dark Sky is not reporting “clear” conditions. Not perfect but good enough for me so far.


That would probably work as well as the WU data. If you look at the implementation you’ll see there’s a mapping from a dozen or so conditions to illuminance values. I’ll look into it. Thanks!


First time using custom components, I tried your instruction and HA’s Hello World example, both cases gave error in log about Unable to find component sensor.xxx, Platform not found: sensor.xxx

Would you know why my HA (hassbian) doesn’t work with custom components?


Can you provide the exact error message?

A couple things to check. First, are you sure you created the custom_components folder in the right place? It should be in your HA config folder. E.g., mine is /home/homeassistant/.homeassistant, so it should be /home/homeassistant/.homeassistant/custom_components. If you’re not sure where you HA config folder is, go to the Info page in the frontend. Right under the HA version it will show it, labeled Path to configuration.yaml:.

Also, make sure this folder, sub-folders, and files have permissions set so the homeassistant user (or whatever is appropriate for your install) can access them.


Thanks for getting back to me.

It was file permission. The Hello World HA example works correctly, sensor.example reports value. But now there is error coming from inside the illuminiance.py:

Log Details (ERROR)
Thu May 24 2018 10:40:53 GMT-0400 (Eastern Daylight Time)

Error while setting up platform illuminance
Traceback (most recent call last):
File “/srv/homeassistant/lib/python3.5/site-packages/homeassistant/helpers/entity_platform.py”, line 129, in _async_setup_platform
SLOW_SETUP_MAX_WAIT, loop=hass.loop)
File “/usr/lib/python3.5/asyncio/tasks.py”, line 400, in wait_for
return fut.result()
File “/usr/lib/python3.5/asyncio/futures.py”, line 293, in result
raise self._exception
File “/usr/lib/python3.5/asyncio/tasks.py”, line 239, in _step
result = coro.send(None)
File “/home/homeassistant/.homeassistant/custom_components/sensor/illuminance.py”, line 59, in async_setup_platform
config[CONF_NAME], session, api_key, query)], True)
KeyError: ‘name’

Does that has to do with your update note:

Update 5/14/2018 3:30 PM CDT - Abort update (and log error) if current observation icon (which algorithm is based on) is empty or is an unexpected value. Previously this caused an illuminance value of zero.

Here is my config:
- platform: illuminance
api_key: !secret wunderground_api
query: ‘pws:KMIPORTA12’
minutes: 5


No. I probably need to enhance the config schema. Basically it’s expecting you to add name: to your config.


I was looking at the Dark Sky API and it doesn’t appear that they provide a luminance value. The closest useful datum might be ‘cloud cover’ which gives a value from 0 to 1. I suppose one could calculate a luminance proxy from sun elevation, time of day and the cloud cover value, but my coding skills are not up to the task.


I recently added cloudiness to the monitored conditions of the YR platform I had set up (from the default config.) It basically reports the same thing. But after a few days I can see there’s not a very good correlation. I even searched the Internet (briefly) for info about how cloudiness might translate to illuminance, and the little I found seemed to imply it’s not a very good relation. E.g., cloudiness is usually just a percentage of how much sky is occluded, but nothing about how thick the clouds are.

But I believe Dark Sky has a weather icon, I would assume like WU, but I haven’t yet looked into it.


Yes, you’re right, just needed to add “name” in the sensor config.
Thanks for helping.:fu:


Moved code to github.

Also note that currently the platform configuration parameter name is required (contrary to what it says above.) I plan to fix that and make it truly optional soon.

EDIT: Fixed. Update in github. Default name is now Illuminance.


Hi all is steup properly but I keep getting an WU API error “no cities match your query,.”

I triple checked and the pws ID is correct.

Any clue?


  • name: Illuminance
    platform: illuminance
    api_key: !secret wu_apikey
    query: ‘pws:IBRACCIA6’
    minutes: 5


any clue?


No, no clue. It looks right to me (although it would help if you formatted your configuration per the instructions at the top of the page.) For example, I just tried this:

curl 'http://api.wunderground.com/api/my_api_key/conditions/q/pws:IBRACCIA6.json'

with my_api_key replaced with my actual api key, and it worked fine for me. That’s basically the URL that illuminance.py would use.