OpenUV

The OpenUV integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] displays UV and Ozone data from openuv.io.

Generating an API Key

To generate an API key, log in at the OpenUV website.

Configuration

To add the OpenUV service to your Home Assistant instance, use this My button:

Sensors

Updating data

Beginning February 1, 2019, the “Limited” plan (which is what new users are given by default) is limited to 50 API requests per day. Because different API plans and locations will have different requirements, the OpenUV integration does not automatically query the API for new data after it initially loads. To request new data, the homeassistant.update_entity action should be used.

Note that in the case of UV and ozone data, selecting any one of:

• Current Ozone Level
• Current UV Index
• Current UV Level
• Max UV Index
• Skin Type 1 Safe Exposure Time
• Skin Type 2 Safe Exposure Time
• Skin Type 3 Safe Exposure Time
• Skin Type 4 Safe Exposure Time
• Skin Type 5 Safe Exposure Time
• Skin Type 6 Safe Exposure Time

…as the target for the homeassistant.update_entity action will update the data for all of these entities.

To protect against possible API call waste, all calls to homeassistant.update_entity that reference an OpenUV entity are throttled to a minimum of 15 minutes between calls.

Protection window

The Protection Window binary sensor will be on when sunblock protection should be used.

By default, this occurs anytime the UV index is above 3.5. This behavior can be configured via the config entry options within the UI. Two parameters are given:

• Starting UV index for the protection window: the UV index that, when passed, indicates protection should be utilized
• Ending UV index for the protection window: the UV index that, when passed, indicates protection is no longer required

Examples of Updating Data

Update the UV index data every 20 minutes while the sun is at least 10 degrees above the horizon:

automation:
  - alias: "Update OpenUV"
    triggers:
      - trigger: time_pattern
        minutes: "/20"
    conditions:
      - condition: numeric_state
        entity_id: sun.sun
        value_template: "{{ state.attributes.elevation }}"
        above: 10
    actions:
      - action: homeassistant.update_entity
        target:
          entity_id: sensor.LATITUDE_LONGITUDE_current_uv_index

Update the protection window once a day at 12:00pm:

automation:
  - alias: "Update OpenUV"
    triggers:
      - trigger: time
        at: "12:00:00"
    actions:
      - action: homeassistant.update_entity
        target:
          entity_id: binary_sensor.LATITUDE_LONGITUDE_protection_window

For a reusable schedule that limits updates to daylight hours, use the following blueprint. It supports refresh intervals of 15, 30, 45, or 60 minutes and allows one final refresh shortly after sunset.

Prefer to configure this automation manually? Use the YAML below.

alias: Refresh OpenUV data during daylight
trigger_variables:
  refresh_interval: '45'

triggers:
  - trigger: time_pattern
    minutes: "/15"

conditions:
  - condition: sun
    after: sunrise
    before: sunset
    before_offset: "+00:45:00"
  - condition: template
    value_template: >-
      {{ (((as_timestamp(now()) // 60) | int) % (refresh_interval | int)) == 0 }}

actions:
  - action: homeassistant.update_entity
    target:
      entity_id: YOUR_ENTITIES

Expired API Keys and Re-authentication

In OpenUV, an HTTP 403 response indicates one of two conditions:

1. An invalid API key
2. An API key whose daily/monthly limit is reached

Unfortunately, the integration is unable to determine which is which from the API data provided by OpenUV. So, this strategy is followed:

1. Any HTTP 403 response will create a persistent notification asking you to re-authenticate the OpenUV integration.
2. In the case of an overrun API call limit, once the homeassistant.update_entity action is again successful, existing re-authentication notifications will automatically be removed.

If you receive a re-authentication notification and are certain that your key has merely reached its daily call limit, you can safely ignore it.