Connects Home Assistant to the OpenPlantbook API for searching plant species, fetching care data, and uploading sensor readings. Used as the data backend for the Plant Monitor integration.

• 🌿 OpenPlantbook Integration for Home Assistant
  • 📦 Installation
  • 🔧 Setup
  • ⚙️ Configuration Options
    • 📤 Upload Plant Sensor Data
    • 🌍 Share Location
    • 🌐 International Common Names
    • 🖼️ Automatically Download Images
  • 📡 Actions (Service Calls)
  • 🖥️ GUI Example
  • ☕ Support

1. Add this repo as a Custom Repository with type Integration
2. Click Download in the "OpenPlantbook" card in HACS
3. Restart Home Assistant

1. Copy custom_components/openplantbook/ to your <config>/custom_components/ directory
2. Restart Home Assistant

You need an OpenPlantbook account (free) with API credentials.

1. Register at open.plantbook.io
2. Find your client_id and secret at https://open.plantbook.io/apikey/show/
3. In Home Assistant: Settings → Devices & Services → Add Integration → OpenPlantbook
4. Enter your credentials — the integration validates them and shows an error if incorrect
5. Configure upload settings (optional but recommended)

After setup, click Configure on the integration card to access additional options.

When enabled, the integration periodically (once a day) uploads sensor data from your plants to OpenPlantbook. This helps build a useful community dataset. More info: https://open.plantbook.io/ui/sensor-data/

• First upload: last 24 hours of data
• If sensors are disconnected, it retries daily for up to 7 days of historical data
• Can also be triggered manually via the openplantbook.upload action
• Daily uploads are scheduled at a randomized time-of-day per installation (stable for a given config entry) to even load distribution

Optionally share your Home Assistant location to complement sensor data. Two levels:

Location is configured in HA under Settings → System → General.

When enabled, the integration sends your Home Assistant language to OpenPlantbook so the API can return common names in that language when available.

More information about this OpenPlantbook feature.

Available in the integration's Options (click Configure after setup).

• Default path: /config/www/images/plants
• Specify any directory the HA user has write access to
• Relative paths are relative to your config directory

Path behavior:

• If the path contains www/ → image_url is replaced with a /local/ reference
• If the path does not contain www/ → the full OpenPlantbook URL is kept

Search for plants matching a string:

action: openplantbook.search
data:
  alias: Capsicum

Read results from openplantbook.search_result:

Number of plants found: {{ states('openplantbook.search_result') }}
{%- for pid in states.openplantbook.search_result.attributes %}
  {%- set name = state_attr('openplantbook.search_result', pid) %}
  * {{ pid }} -> {{ name }}
{%- endfor %}

Example output:

Number of plants found: 40
  * capsicum annuum -> Capsicum annuum
  * capsicum baccatum -> Capsicum baccatum
  * capsicum chinense -> Capsicum chinense
  (...)

Get detailed data for a single species:

action: openplantbook.get
data:
  species: capsicum annuum

Read results from openplantbook.capsicum_annuum:

Details for plant {{ states('openplantbook.capsicum_annuum') }}
* Max moisture: {{ state_attr('openplantbook.capsicum_annuum', 'max_soil_moist') }}
* Min moisture: {{ state_attr('openplantbook.capsicum_annuum', 'min_soil_moist') }}
* Max temperature: {{ state_attr('openplantbook.capsicum_annuum', 'max_temp') }}
* Image: {{ state_attr('openplantbook.capsicum_annuum', 'image_url') }}

Manually trigger uploading of plant sensor data:

action: openplantbook.upload

Returns null if nothing was uploaded or an error occurred. Check the HA log for details.

An example of using the actions to build a plant search UI in Home Assistant:

For a full walkthrough with helpers, automations, and Lovelace cards, see examples/GUI.md.