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. To set up plant monitoring and tracking of your plant related sensors, you need to install that integration.
OpenPlantbook is in the default catalog of the Marketplace (HACS before Home Assistant 2026.11).
- Select the button above, or open Settings → Marketplace (HACS before 2026.11) and search for "OpenPlantbook"
- Click Install (Download in HACS)
- Restart Home Assistant
Note
Until November 2026 the catalog listed a fork of this repository, slaxor505/home-assistant-openplantbook. If you installed the fork, uninstall it in the Marketplace (or HACS), install this repository, and restart. Both use the domain openplantbook, so your OpenPlantbook configuration is kept.
- Copy
custom_components/openplantbook/to your<config>/custom_components/directory - Restart Home Assistant
You need an OpenPlantbook account (free) with API credentials.
- Register at open.plantbook.io
- Find your
client_idandsecretat https://open.plantbook.io/apikey/show/ - In Home Assistant: Settings → Devices & Services → Add Integration → OpenPlantbook
- Enter your credentials — the integration validates them and shows an error if incorrect
- Configure upload settings (optional but recommended)
After setup, click Configure on the integration card to access additional options.
Note
All data is shared anonymously.
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.uploadaction - Daily uploads are scheduled at a randomized time-of-day per installation (stable for a given config entry) to even load distribution
Three diagnostic entities on the OpenPlantbook device show how uploads are going:
- Upload problem (binary sensor): on while uploads need attention - the latest upload failed or hit the rate limit, no data has reached OpenPlantbook for 3 days, or a plant cannot be registered. Its attributes say why (
reason:failed,rate_limited,overdueorplants_failed) and list the plants that cannot be registered. A plant stays on that list until it registers again. The sensor is unavailable while uploading is off. - Upload status: how the latest run went -
uploaded,nothing_new,failed,rate_limited, ordisabledwhen uploading is off - with the time of the run, the plants that could not be registered, and the error. - Last upload: when data last reached OpenPlantbook, from a successful run or from OpenPlantbook's own record.
On Home Assistant 2026.7 or later there are triggers for automations: openplantbook.upload_problem_started and openplantbook.upload_problem_cleared, which fire when Upload problem turns on and off. On older versions, use a state trigger on that sensor.
The triggers fire when the sensor changes from off to on (or back). A problem that begins while Home Assistant is down, or that is already there when you turn uploading back on, shows on the sensor but does not fire them. To be told about it after a restart, check the sensor when Home Assistant starts:
triggers:
- trigger: homeassistant
event: start
conditions:
- condition: state
entity_id: binary_sensor.openplantbook_upload_problem
state: "on"
actions:
- action: notify.mobile_app_phone
data:
message: "OpenPlantbook uploads need attention"The OpenPlantbook upload problem blueprint uses both - pick what should happen, such as a notification:
Optionally share your Home Assistant location to complement sensor data. Two levels:
| Option | What is shared |
|---|---|
| Country only | Country from HA configuration |
| Coordinates | Lat/lon from HA configuration |
Location is configured in HA under Settings → System → General.
Tip
Enable DEBUG logging for the integration to see exactly what data is being shared.
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_urlis replaced with a/local/reference - If the path does not contain
www/→ the full OpenPlantbook URL is kept
Note
Existing files are never overwritten. The target directory must exist before configuring.
Search for plants matching a string:
action: openplantbook.search
data:
alias: CapsicumRead 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 annuumNote
The species string must match exactly the pid returned by openplantbook.search.
Request additional categories with the optional include parameter (comma-separated). Currently the API supports care, which adds watering, sunlight, soil, pruning, and fertilization:
action: openplantbook.get
data:
species: monstera deliciosa
include: careThe extra fields are merged into the same entity and returned in the service response. Cached entries remember which categories they already contain, so requesting care for a plant that was previously fetched without it triggers a fresh API call.
After an include: care call, the care fields are available as attributes on the entity:
* Watering: {{ state_attr('openplantbook.monstera_deliciosa', 'watering') }}
* Sunlight: {{ state_attr('openplantbook.monstera_deliciosa', 'sunlight') }}
* Soil: {{ state_attr('openplantbook.monstera_deliciosa', 'soil') }}
* Pruning: {{ state_attr('openplantbook.monstera_deliciosa', 'pruning') }}
* Fertilization: {{ state_attr('openplantbook.monstera_deliciosa', 'fertilization') }}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.uploadReturns 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:
Note
This UI is not part of the integration — it's an example of what you can build with the actions.
For a full walkthrough with helpers, automations, and Lovelace cards, see examples/GUI.md.
