ClimaCell weather service provider integration

... is a custom component (sensor) for Home Assistant.

The ClimaCell platform uses the ClimaCell API version 4 as a source for meteorological data for your location.

To use this component you must obtain an API version 4 key. Visit the ClimaCell site to learn how to obtain one.

WARNING

In December 2020, Climacell released released version 4 of ClimaCell API and announced that version 3 will be sunset on July 1, 2021. On this date, all requests made against v3 will fail. For more details read on ClimaCell

This new component version is based on Climacell API version 4 and is not backward compatible with the previous component (based on Climacell API version 3 ). The ClimaCell API version 3 are fundamentally different from API version 4, they contains two different set of sensors. Please check the differences before use: ClimaCell Layers Overview

Migration from previous component version (based on API version 3)

To make the integration API V4 compatible it has been largely restructured. We tried to make it backward compatible regarding configuration and sensor names but there might be some corner cases where the sensor names change when upgrading.

The API version 3 authorization key don't work with the API version 4. If you use an API version 3 authorization key then you must retrieve a new authorization key, visit the ClimaCell site to learn how to obtain one.

Manual installation

1. Using the tool of choice, open the directory (folder) of your HA configuration (there you can find configuration.yaml).
2. If you do not have a custom_components directory (folder) there, you need to create one.
3. In the custom_components directory (folder) create a new folder called climacell.
4. Download all the files from this repository.
5. Place the content of the custom_components/climacell/ directory (folder) in the new directory (folder) you created.

Configuration

To use the ClimaCell custom component you must first obtain an v4 API key.

Sensor variables

api_key

(string)(Required)
Your API key.

name

(string)(Optional)
Additional name for the sensors. PS The name of the sensor always starts with the prefix cc

Default value:
climacell

latitude

(float)(Optional)
Latitude coordinate to monitor weather of (required if longitude is specified).

Default value:
coordinates from the Home Assistant configuration

longitude

(float)(Optional)
Longitude coordinate to monitor weather of (required if latitude is specified).

Default value:
Coordinates from the Home Assistant configuration

units

(string)(Optional)
Specify the unit system. Valid options are imperial, metric.

Default value:
metric or us, based on the temperature preference in Home Assistant

timelines

(object list)(Required)
List of timeline specification. Each list item is an object with the following variables.

name

(string)(Required)
Name of timeline used for naming the sensors.

fields

(string list)(Required)
Conditions to view. These depend on the type of service, see the section below for more details.

timestep

(string)(Optional)
Step length for observations consisting of an integer value followed by 'm' for minute, 'h' for hour or 'd' for day.

Default value:
1d

forecast_observations

(integer)(Optional)
Number of timesteps for which you would like to receive forecast.

Default value:
5

scan_interval

(time)(Optional)
Minimum time interval between updates.

Default value:
5 minutes

exclude_interval

(array of object)(Optional)
Intervals excluded from the update to use to reduce the number of the API calls. Each interval consists of a pair of values and indicates the start and end of the update exclusion. In particular you can specify from 1 to 20 different ranges.

Example

exclude_interval:

 1:      # range

  - "23:30" # start

  - "06:00" # end

Default value:
None

start_time

(integer)(Optional)
Number of minutes in future (+) or past (-) from the current time to start the timeline. The availability depends on timestep and requested fields.

Default value:
0

Condition information

The available Fields and suffixes can be found in the climacell dodumentation. The old field names can still be used.

You can put the suffixes "Max", "Min", "Avg", "MaxTime" or "MinTime" at the end of the field name to get the maximum, minimum, average, time of maximum and time of minimum in the selected timestep respectively. So to get the maximum temperature you would use the field temperatureMax.

For mapped values (e.g. weatherCode) the prefix "Raw" will disable mapping.

Integration Examples

sensor:
  # Weather climatecell.co
  - platform: climacell
    api_key: !secret climacell_api_key
    name: example
    latitude: !secret gps_geo_home_lt
    longitude: !secret gps_geo_home_ln
    units: metric
    timelines:
      - name: "" #Realtime
        timestep: "1m"
        forecast_observations: 1
        fields:
          - temperatureMax
          - feels_like
          - humidity
          - wind_speed
          - wind_direction
          - wind_gust
          - pressure
          - precipitationIntensity
          - precipitation_type
          - visibility
          - cloud_cover
          - weather_condition
          - pm25
          - pm10
          - o3
          - no2
          - co
          - so2
          - epa_aqi
          - epa_health_concern
          - pollen_tree
          - pollen_weed
          - pollen_grass
          - fire_index
        update: auto
        scan_interval:
          # At least one of these must be specified:
          days: 0
          hours: 1
          minutes: 0
          seconds: 0
          milliseconds: 0
        exclude_interval:
          1:
            - "00:00"
            - "07:00"
      - name: "" #Daily
        timestep: "1d"
        forecast_observations: 5
        fields:
          - temperature
          - temperatureMin
          - temperatureMax
          - precipitationIntensityMin
          - precipitationIntensityMax
          - precipitation_probability
          - weather_condition
        scan_interval:
          # At least one of these must be specified:
          days: 0
          hours: 4
          minutes: 0
          seconds: 0
          milliseconds: 0
        exclude_interval:
          1:
            - "23:00"
            - "06:30"

The climacell custom component exposes a sensor for each monitored condition. An example of data provided by a climacell sensor is the following:

Sensor name	State	Sensor attributes	Value
cc_temperature	13.2	attribution	Powered by Climacell
		unit_of_measurement	C
		observation_time	2020-04-30T02:40:47.390Z
		friendly_name	Temperature
		icon	mdi:thermometer