Homeassistant Community Forum Thread: https://community.home-assistant.io/t/barcelona-catalunya-beach-bathing-costal-weather-integration/950046

Monitor Catalan beaches with real-time water quality, weather conditions, and safety information from the Catalan Water Agency (Agència Catalana de l'Aigua).

• 15 Entity Types across sensors and binary sensors
• Multi-language Support (English and Catalan)
• Configurable Updates (15 minutes to 24 hours)
• Dynamic Entity Selection - enable only the sensors you need
• Force Refresh - update data on demand
• Beach-specific Devices - organize all entities under each beach

• Water Temperature (°C) - Current sea temperature
• Air Temperature (°C) - Current air temperature at the beach
• Water Quality - Classification from Excellent to Very Poor
• UV Index - Sun exposure risk level
• Wave Height (m) - Current wave conditions
• Wind Speed (km/h) - Wind conditions
• Sky Condition - Weather status (Clear, Cloudy, Rain, etc.)
• Jellyfish Status - Presence level (None to Very High)
• Last Water Test Date - When quality was last checked
• Beach Description - General information about the beach

• Lifeguard Present - Safety: Is a lifeguard on duty?
• Out of Season - Problem: Is the beach closed for the season?
• Water Quality Good - Is water quality acceptable or better?
• Jellyfish Alert - Problem: Moderate or higher jellyfish presence
• Rain Risk High - Problem: Is rain likely?

1. Open HACS in Home Assistant
2. Go to "Integrations"
3. Click the three dots (⋮) and select "Custom repositories"
4. Add https://github.com/tamaygz/ha-catalunya-beaches as an Integration
5. Click "Download"
6. Restart Home Assistant

1. Download the latest release from GitHub
2. Copy the custom_components/ha-catalunya-beaches folder to your Home Assistant's custom_components directory
3. Restart Home Assistant

1. Go to Settings → Devices & Services
2. Click Add Integration
3. Search for "Catalunya Beaches"
4. Follow the configuration flow:

Choose your preferred language for beach information (English or Catalan)

Select a beach from the list fetched from the Catalan Water Agency API

• Select which entities to enable (default: all enabled)
• Set the update interval (default: 1 hour, range: 15 minutes to 24 hours)

After setup, you can modify configuration:

1. Go to Settings → Devices & Services
2. Find "Catalunya Beaches"
3. Click Configure

Available options:

• Update Interval - Change how often data is fetched
• Enabled Entities - Add or remove entities
• Force Refresh - Immediately update all data
• Delete Historical Data - Remove all stored history for this beach

Alert when water quality drops:

automation:
  - alias: "Beach Water Quality Alert"
    trigger:
      - platform: state
        entity_id: binary_sensor.platja_de_barcelona_water_quality_good
        to: "off"
    action:
      - service: notify.mobile_app
        data:
          message: "Water quality at your beach is not good!"

Check if it's a good beach day:

template:
  - binary_sensor:
      - name: "Good Beach Day"
        state: >
          {{ is_state('binary_sensor.platja_de_barcelona_lifeguard_present', 'on')
             and is_state('binary_sensor.platja_de_barcelona_water_quality_good', 'on')
             and is_state('binary_sensor.platja_de_barcelona_rain_risk_high', 'off')
             and states('sensor.platja_de_barcelona_water_temperature')|float > 20 }}

Beach overview card:

type: entities
title: Platja de Barcelona
entities:
  - sensor.platja_de_barcelona_water_temperature
  - sensor.platja_de_barcelona_air_temperature
  - sensor.platja_de_barcelona_water_quality
  - binary_sensor.platja_de_barcelona_lifeguard_present
  - binary_sensor.platja_de_barcelona_jellyfish_alert
  - sensor.platja_de_barcelona_uv_index

Beach map card:

type: map
title: Catalunya beaches
auto_fit: true
entities:
  - entity: sensor.platja_de_barcelona_beach_name
    label_mode: state   # or "icon" for dynamic warning icons

The Beach Name sensor is the single map-capable entity per beach. It includes latitude/longitude, a beach_status summary attribute ("OK" or comma-separated warnings), active_warnings list, water_quality, and jellyfish attributes. The sensor icon changes dynamically based on the worst active warning (default mdi:beach, jellyfish → mdi:jellyfish, poor water → mdi:water-alert, out of season → mdi:calendar-remove).

Map pin modes:

• label_mode: state — shows the beach name text
• label_mode: icon — shows the dynamic warning icon
• label_mode: attribute with attribute: beach_status — shows warning summary
• omit label_mode — shows the beach photo (entity_picture) as the pin image

Beach images and status icons detected from the API are cached locally in Home Assistant under:

• /config/www/ha-catalunya-beaches/<beach_id>/<filename>

When cached, related sensor attributes and entity_picture expose token-free URLs:

• /local/ha-catalunya-beaches/<beach_id>/<filename>

This makes Bubble Card / Markdown / Picture cards render reliably without /api/...token= URLs.

Security notes: Assets are fetched exclusively over HTTPS. Only JPEG, PNG, GIF, and WebP content types are accepted (SVG and other types are blocked). Downloads are capped at 5 MB per file. At most 4 files are fetched concurrently per refresh cycle.

This integration uses the official Catalan Water Agency (Agència Catalana de l'Aigua) API:

• Beach list endpoint: https://aplicacions.aca.gencat.cat/platges/AppJava/api/front/{language}
• Beach details endpoint: https://aplicacions.aca.gencat.cat/platges/AppJava/api/playadetalle/{beach_id}/{language}

Data is updated according to your configured interval (default: 1 hour). The API provides official government data about beach conditions across Catalonia.

• Check your Home Assistant logs for errors
• Verify internet connectivity to the Catalan government API
• Try restarting Home Assistant

• Wait for the first update cycle to complete
• Try using "Force Refresh" in the integration options
• Check if the beach API is accessible from your network

• Verify the entities are enabled in the integration options
• Some beaches may not have all data available
• Check that the entity hasn't been disabled in the entity registry

Contributions are welcome! Please read CONTRIBUTING.md for guidelines.

This project is licensed under the MIT License - see the LICENSE file for details.

• Data provided by Agència Catalana de l'Aigua
• Built with the Home Assistant Integration Blueprint