Unsplash Wallpapers for Home Assistant

README.md

Unsplash for HA

Using RESTful Integration and Template Image helpers

I put this together to avoid having to write a full integration as a provider. I think it'd be fun to put one together to allow better selecting topics and the like, but for now this works.

1. Get your application

First, you'll need to register your application at Unsplash if you don't have one. Visit the documentation here to learn about this process.

Once you have your application access token, make sure to add it to your secrets.yaml file in the format of "Client-ID <your_token>", so that !secret unsplash_access will include the Client-ID portion.

2. Pick a topic

This part really relies on the API at https://api.unsplash.com/topics but has to be authenticated, and can be a bit laborious to explore, since these aren't visible IDs in the front-end of unsplash.com.

Here's a few to get you started:

[{'id': 'bo8jQKTaE0Y', 'title': 'Wallpapers'},
 {'id': 'CDwuwXJAbEw', 'title': '3D Renders'},
 {'id': '6sMVjTLSkeQ', 'title': 'Nature'},
 {'id': 'iUIsnVtjB0Y', 'title': 'Textures'},
 {'id': 'hmenvQhUmxM', 'title': 'Film'},
 {'id': 'M8jVbLbTRws', 'title': 'Architecture'},
 {'id': 'xHxYTMHLgOc', 'title': 'Street Photography'},
 {'id': 'qPYsDzvJOYc', 'title': 'Experimental'},
 {'id': 'Fzo3zuOHN6w', 'title': 'Travel'},
 {'id': 'towJZFskpGg', 'title': 'People'},
 {'id': 'qtLUDvcrXVc', 'title': 'Winter'},
 {'id': 'If65AuNOOxQ', 'title': 'Wallpapers'},
 {'id': 'M4lsf7LQDRA', 'title': 'Nature'},
 {'id': 'vFcvoGKLoaw', 'title': 'Business & Tech'},
 {'id': 'MXYPPfPdkcw', 'title': 'Food & Drink'},
 {'id': 'DJY86N98I0c', 'title': 'People'},
 {'id': 'upmleWZC83Y', 'title': 'Patterns'},
 {'id': 'whIY33yKE84', 'title': '3D'},
 {'id': 'Jpg6Kidl-Hk', 'title': 'Animals'},
 {'id': 'S4MKLAsBB74', 'title': 'Fashion & Beauty'},
 {'id': 'pIF7l5_hgxg', 'title': 'Flat'},
 {'id': 'tthdwfNPCcw', 'title': 'Hand Drawn'},
 {'id': 'FkTvWj0W5bo', 'title': 'Icons'},
 {'id': 'rNbj3NBAY_w', 'title': 'Line Art'},
 {'id': 's6S1wLw6TAA', 'title': 'Spring'}]

Replace the topic: param value in the rest.yaml file with the relevant ID.

3. Add rest.yaml to your configuration

If you already have a rest: entry in your configuration.yaml file, you can add it to that, whether in the single file or a separate one.

Otherwise, save the below after editing to rest.yaml and add a rest: !include rest.yaml line in your configuration.yaml file.

Restart Home Assistant after all of this.

4. Add an image helper

Go to your Settings->Devices->Helpers and add a new helper. Select 'Template', then 'Image'.

Make the name 'Unsplash Random Photo Image'.

Make sure the URL field matches the following, assuming you kept the name the same:

{{ state_attr('sensor.unsplash_random_photo','entity_picture') }}

And save it.

5. Make background!

Normal Dashboards

Go to your dashboard and go to edit mode, then edit the current page. Go to the 'Background' tab and click 'select from media'.

Then go to Image, and select your new image!

This will only set it for the current page. If you want to add this to the entire dashboard:

Before saving, click the triple-dot button and 'Edit in YAML'. Cut the entire background: block to your clipboard, like below:

Save/close, then go to the triple-dot while still in edit mode for the dashboard and go to 'Raw configuration editor', and paste the block in at the root level of the entire dashboard configuration, easily just the top line.

View Assist dashboards

You can use this for View Assist, too! Go to configure either the main 'master' configuration or per-device and go to Dashboard Options, and expand 'Background'. Change it to 'Custom URL' and add the following to both lines, changing the entity ID if needed: /api/image_proxy_stream/image.unsplash_random_photo_image

6. Done!

Enjoy! If you want to change the refresh speed just update the scan_interval: key of the rest: configuration here to the frequency in seconds. Be aware you only get 50 API calls per hour for free, so it should not be any lower than 120 to limit to 30 calls or less.

This also includes some attributes with information about the image. The default sensor for the photo is the description rather than the URL itself, but the entity picture is being set to the URL. You could also change 'raw' for ultra high resolution or 'regular' for a 1080 image. You could even add an orientation: param for 'landscape', 'portrait', or 'squarish' to pull an appropriately-shaped image if wishing to limit to such.

rest.yaml

- resource: https://api.unsplash.com/photos/random
  scan_interval: 600
  headers:
    authorization: !secret unsplash_access
  params:
    content_filter: low
    topics: 6sMVjTLSkeQ
  sensor:
    - name: "Unsplash Random Photo"
      value_template: "{{ value_json.alt_description }}"
      picture: "{{ value_json.urls.full }}"
      json_attributes:
        - id
        - slug
        - description
        - width
        - height
        - created_at
        - updated_at
        - promoted_at
        - color
        - blur_hash
    - name: "Unsplash Random Photo User Information"
      json_attributes_path: "$.user"
      value_template: "{{ value_json.user.name }}"
      picture: "{{ value_json.user.profile_image.large }}"
      json_attributes:
        - id
        - username
        - first_name
        - last_name
        - portfolio_url
        - bio
        - location