---
title: OpenUV
description: Instructions on how to integrate OpenUV within Home Assistant.
ha_category:
  - Binary Sensor
  - Health
  - Sensor
ha_release: 0.76
ha_iot_class: Cloud Polling
ha_config_flow: true
ha_codeowners:
  - '@bachya'
ha_domain: openuv
ha_platforms:
  - binary_sensor
  - diagnostics
  - sensor
ha_integration_type: integration
---

The `openuv` integration displays UV and Ozone data from [openuv.io](https://www.openuv.io/).

<div class='note warning'>
The guidelines within this documentation constitute estimates and are intended to help
informed decision making. They should not replace analysis, advice or diagnosis from a
trained medical professional.
</div>

## Generating an API Key

To generate an API key,
[simply log in to the OpenUV website](https://www.openuv.io/auth/google).

<div class='note warning'>
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`
component does not automatically query the API for new data after it initially
loads. To request new data, the `update_data` service may be used.
</div>

<div class='note warning'>
Each use of the `update_data` service will consume 2 API calls from the daily quota
(since it performs the same tasks as back-to-back calls of the `update_uv_index_data` and
the `update_protection_data` services).
</div>

{% include integrations/config_flow.md %}

## Sensors

| Name | Type | Value |
|------|------|-------|
| Current Ozone Level | Sensor | ozone level in du (Dobson Units) |
| Current UV Index | Sensor | UV Index (numerical value) |
| Current UV Level | Sensor | UV Level (as literal) |
| Max UV Index | Sensor | max UV Index for the day (at solar noon) |
| Protection Window | Binary Sensor | whether sunblock protection should be used |

### 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

### The Fitzpatrick Scale

The approximate number of minutes of a particular skin type can be exposed to
the sun before burning/tanning starts is based on the
[Fitzpatrick scale](https://en.wikipedia.org/wiki/Fitzpatrick_scale).

OpenUV integration provide sensors for safe exposure time (in minutes) based on skin type:

- 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

## Services

### `openuv.update_data`

Perform an on-demand update of OpenUV data.

### `openuv.update_uv_index_data`

Perform an on-demand update of OpenUV sensor data including current UV index, but not the `uv_protection_window`, saving an API call over `update_data`.

### `openuv.update_protection_data`

Perform an on-demand update of OpenUV `uv_protection_window` data, but not the sensors, saving an API call.

## Examples of Updating Data

To perform an optimal amount of API calls you need to know the hours of daylight on the longest day of the year. If for example this is 17 hours, you can perform 2 calls around every 45 minutes without running into the 50 API call limit per day:

{% raw %}

```yaml
automation:
  - alias: "Update OpenUV"
    trigger:
      # Time pattern of /45 will not work as expected, it will trigger on the whole hour and on the whole hour + 45 minutes.
      # Using more frequent time pattern and a condition to get the intended behavior.
      - platform: time_pattern
        minutes: "/15"
    condition:
      - condition: sun
        after: sunrise
        before: sunset
        # The last call will most likely fall before the sunset, thus leaving an UV index value not at 0 for the remaining night.
        # To fix this, we allow one more service call after the sun has set.
        before_offset: "+00:45:00"
      # We check if the last trigger has been 40 minutes or more ago so we don't run into timing issues.
      # By checking for 40 minutes or greater we ensure this is only true at the 45 minute mark.
      - condition: template
        value_template: >- 
          {{
            state_attr('automation.openuv_update', 'last_triggered') == None or
            (now() - state_attr('automation.openuv_update', 'last_triggered')) >= timedelta(hours = 0, minutes = 40)
          }}
    action:
      - service: openuv.update_data

```

{% endraw %}

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

{% raw %}

```yaml
automation:
  - alias: "Update OpenUV every 20 minutes while the sun is at least 10 degrees above the horizon"
    trigger:
      platform: time_pattern
      minutes: "/20"
    condition:
      condition: numeric_state
      entity_id: sun.sun
      value_template: "{{ state.attributes.elevation }}"
      above: 10
    action:
      service: openuv.update_uv_index_data
```

{% endraw %}

Update the protection window once a day:

```yaml
automation:
  - alias: "Update OpenUV protection window once a day"
    trigger:
      platform: time
      at: "02:12:00"
    action:
      service: openuv.update_protection_data
```

Another method (useful when monitoring locations other than the Home Assistant latitude
and longitude, in locations where there is a large amount of sunlight per day,
etc.) might be to simply query the API less often:

```yaml
automation:
  - alias: "Update OpenUV every hour (48 of 50 calls per day)"
    trigger:
      platform: time_pattern
      hours: "*"
    action:
      service: openuv.update_data
```