Electricity Maps

The Electricity Maps integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] (formerly known as CO2Signal) queries the Electricity Maps API for the CO2 intensity of a specific region. Data can be collected for your home by using the home location, latitude/longitude, or a country code.

This API uses the same data as shown on the Electricity Maps app. Not all countries/regions in the world are supported, so please check the app to verify local availability before setting up the integration.

Use case

The Electricity Maps integration helps you understand the carbon intensity of your electricity grid in real-time. This information can be valuable for:

• Timing energy-intensive tasks (like charging electric vehicles or running appliances) during periods of lower carbon intensity.
• Creating automations that respond to changing grid conditions.
• Visualizing your region’s progress towards cleaner energy.
• Understanding how weather conditions affect renewable energy availability in your area.
• Tracking the carbon impact of your home’s energy usage in the Energy Dashboard.

Prerequisites

To configure and use this integration, you need to obtain a free API key from Electricity Maps by signing up to the Free Tier product on the Electricity Maps API Portal. Please be aware that the Free Tier API is limited to one location (called a zone). You need to specify the zone for your home location when creating your account.

Configuration

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

The integration provides the following configuration options when setting it up:

When configuring the location based on latitude/longitude, you will be prompted to enter the following:

When configuring the location based on a country code, you will be prompted to enter the following:

Supported functionality

Sensors

The integration creates two sensors for each configured location:

• Carbon intensity: Shows the carbon intensity of electricity production in your area, measured in gCO2eq/kWh (grams of CO2 equivalent per kilowatt-hour).
• Fossil fuel percentage: Shows what percentage of the electricity grid currently relies on fossil fuels for production.

Examples

Creating a dashboard card

You can create a gauge card to visualize the carbon intensity of your electricity:

type: gauge
entity: sensor.electricity_maps_carbon_intensity
name: Carbon Intensity
min: 0
max: 500
severity:
  green: 0
  yellow: 150
  red: 300

Automation example: Run appliances when carbon intensity is low

This automation starts your dishwasher when the carbon intensity drops below a specific threshold:

alias: "Run Dishwasher at Low Carbon Intensity"
description: "Starts the dishwasher when carbon intensity is low"
trigger:
  - platform: numeric_state
    entity_id: sensor.electricity_maps_carbon_intensity
    below: 100
    for:
      minutes: 10
condition:
  - condition: time
    after: "22:00:00"
    before: "06:00:00"
  - condition: state
    entity_id: binary_sensor.dishwasher_ready
    state: "on"
action:
  - service: switch.turn_on
    target:
      entity_id: switch.dishwasher
  - service: notify.mobile_app
    data:
      message: "Dishwasher started during low carbon intensity period ({{ states('sensor.electricity_maps_carbon_intensity') }} gCO2eq/kWh)"

Creating a history graph to track changes

Add this to your dashboard to track how carbon intensity changes throughout the day:

type: history-graph
entities:
  - entity: sensor.electricity_maps_carbon_intensity
    name: Carbon Intensity
hours_to_show: 24
refresh_interval: 60

Energy Dashboard integration

The Electricity Maps integration is automatically used on the Energy Dashboard when set up. The carbon intensity data appears in the Energy Dashboard as a real-time gauge showing the carbon footprint of your household electricity usage.

You don’t need to manually configure anything - the integration is automatically detected and used by the Energy Dashboard to calculate and display your home’s carbon emissions based on your energy consumption and the current grid carbon intensity.

To view this information:

1. Navigate to the Energy Dashboard.
2. Look for the carbon intensity gauge in the dashboard.

If you don’t see the carbon information in your Energy Dashboard:

1. Make sure the Electricity Maps integration is properly set up and working.
2. Verify that you have energy monitoring configured in Home Assistant.

Data updates

The integration pollsData polling is the process of querying a device or service at regular intervals to check for updates or retrieve data. By defining a custom polling interval, you can control how frequently your system checks for new data, which can help optimize performance and reduce unnecessary network traffic. [Learn more] data from the Electricity Maps API every 15 minutes by default. The actual update frequency may be limited by your API tier’s rate limits.

Known limitations

• The Free Tier API is limited to one location. You need to specify the country when creating your account.
• The Free Tier API has a limit of 50 requests per hour, but the integration is designed to poll at a rate that won’t exceed this limit.
• Not all geographic regions are supported by Electricity Maps. Check their app to see if your region has coverage.

Troubleshooting

Integration fails to set up

Symptom: “The given token is invalid” during setup

If you see an invalid token error during setup, your API key may be invalid or expired.

Resolution

1. Verify that you’ve correctly copied the API key from the Electricity Maps API portal.
2. Check if your API key is still active in the Electricity Maps API portal.
3. Try generating a new API key if the issue persists.

Symptom: “No data available for selected location” during setup

If you receive a “No data available for selected location” error, the coordinates or country code you provided might not be supported by Electricity Maps.

Resolution

1. Check the Electricity Maps app to verify coverage for your location.
2. Try using a country code instead of coordinates, or vice versa.
3. If your exact location isn’t supported, try using the nearest supported location.

Sensors show “unavailable”

If your sensors show as “unavailable” after successful setup, there might be issues with the API connection.

Resolution

1. Check your internet connection.
2. Verify that your API key still has available quota for the day.
3. Check if the Electricity Maps service is experiencing downtime.
4. Restart Home Assistant if the issue persists.

Removing the integration

This integration follows standard integration removal. No extra steps are required.

To remove an integration instance from Home Assistant

1. Go to Settings > Devices & services and select the integration card.
2. From the list of devices, select the integration instance you want to remove.
3. Next to the entry, select the three dots menu. Then, select Delete.