https://github.com/faserf/ha-foodsharing
Homeassistant Integration for foodsharing.de
https://github.com/faserf/ha-foodsharing
hacs-integration home-assistant integration
Last synced: 2 months ago
JSON representation
Homeassistant Integration for foodsharing.de
- Host: GitHub
- URL: https://github.com/faserf/ha-foodsharing
- Owner: FaserF
- License: other
- Created: 2022-06-16T16:18:51.000Z (about 4 years ago)
- Default Branch: main
- Last Pushed: 2026-04-14T11:03:15.000Z (3 months ago)
- Last Synced: 2026-04-14T11:25:14.511Z (3 months ago)
- Topics: hacs-integration, home-assistant, integration
- Language: Python
- Homepage:
- Size: 357 KB
- Stars: 3
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Contributing: .github/CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
[](https://github.com/hacs/integration)
[](https://github.com/FaserF/ha-foodsharing/releases)
# Foodsharing.de Home Assistant Integration 🧺
A comprehensive [Home Assistant](https://www.home-assistant.io/) custom integration for [Foodsharing.de](https://foodsharing.de/) — monitor nearby food baskets, fairteiler locations, pickup schedules, messages, and notifications directly from your smart home dashboard. This integration utilizes the official Foodsharing.de API.
---
## Features ✨
| Feature | Description |
|---------|-------------|
| 🧺 **Basket Sensor** | Monitor the number of available food baskets near your location, with full details as attributes |
| 📍 **Fairteiler Sensor** | Monitor the number of nearby Fairteiler locations |
| 📊 **Statistics** | View global, regional, and user-specific Foodsharing statistics (weight saved, rescue missions, etc.) |
| 👥 **Buddies & Bananas** | Track your buddy count and received thanks (bananas) |
| 😴 **Sleeping Hat** | Track your active/sleeping status (vacation mode) |
| 📍 **Geo-Location** | Baskets and Fairteiler points displayed on the HA map with calculated distances |
| 📅 **Pickup Calendar** | Your upcoming pickups shown as calendar events |
| 🔔 **Notifications Sensor** | Track unread bell notifications |
| 💬 **Messages Sensor** | Track unread conversation messages |
| 🔘 **Basket Buttons** | Request nearby baskets or close your own baskets with one tap |
| 🔧 **Service Calls** | `foodsharing.request_basket` service for use in automations |
| 🌍 **Multi-Location** | Add the integration multiple times with different search areas |
| 🔑 **Keyword Matching** | Filter baskets by keywords and get events when matches are found |
| 🩺 **HA Repairs** | Automatic repair notifications for authentication failures or API outages |
| 📊 **Diagnostics** | Built-in diagnostics support with automatic redaction of sensitive data |
| 🌐 **Translations** | Full English and German translations |
---
## ❤️ Support This Project
> I maintain this integration in my **free time alongside my regular job** — bug hunting, new features, testing on real devices. Test hardware costs money, and every donation helps me stay independent and dedicate more time to open-source work.
>
> **This project is and will always remain 100% free.** There are no "Premium Upgrades", paid features, or subscriptions. Every feature is available to everyone.
>
> Donations are completely voluntary — but the more support I receive, the less I depend on other income sources and the more time I can realistically invest into these projects. 💪
[](https://github.com/sponsors/FaserF)
[](https://paypal.me/FaserF)
---
## Installation 🛠️
### 1. Using HACS (Recommended)
This integration is available in the **HACS Default Repository**.
1. Open HACS.
2. Search for **"Foodsharing"**.
3. Click **Download**.
4. Restart Home Assistant.
[](https://my.home-assistant.io/redirect/hacs_repository/?owner=FaserF&repository=ha-foodsharing&category=integration)
### 2. Manual Installation
1. Download the latest [Release](https://github.com/FaserF/ha-foodsharing/releases/latest).
2. Extract the ZIP file.
3. Copy the `foodsharing` folder to `/custom_components/`.
4. Restart Home Assistant.
---
## Configuration ⚙️
1. Go to **Settings** → **Devices & Services**.
2. Click **Add Integration**.
3. Search for **"Foodsharing.de"**.
4. Enter your credentials and select a location on the map.
### Configuration Options
| Option | Description | Default |
|--------|-------------|---------|
| **Email** | Your Foodsharing.de account email | *required* |
| **Password** | Your Foodsharing.de account password | *required* |
| **Location** | Pin on the map to set your search center | HA home location |
| **Search Radius** | Derived from the map circle radius (in km) | 7 km |
| **Keywords** | Comma-separated filter keywords (optional) | *empty* |
| **Scan Interval** | How often to poll the API (in minutes) | 2 min |
> [!TIP]
> You can add the integration multiple times with different locations to monitor several areas at once.
All options can be changed later via **Settings → Devices & Services → Foodsharing → Configure**.
---
## Entities Created 📋
### Sensors
> [!NOTE]
> Statistics and secondary account sensors (Buddies, Bananas, Sleeping Hat, Region Stats) are **disabled by default** to keep your dashboard clean. You can easily enable them in the Home Assistant entity settings if needed.
| Entity | Type | State | Attributes |
|--------|------|-------|------------|
| `sensor.foodsharing_baskets_*` | Sensor | Number of nearby baskets | `baskets` (list), `fairteiler` (list), `basket_count`, `fairteiler_count`, `latitude`, `longitude` |
| `sensor.foodsharing_fairteiler_*` | Sensor | Number of nearby Fairteiler | `fairteiler` (list), `fairteiler_count`, `latitude`, `longitude` |
| `sensor.foodsharing_unread_messages` | Sensor | Number of unread messages | — |
| `sensor.foodsharing_notifications` | Sensor | Number of unread bell notifications | — |
| `sensor.foodsharing_upcoming_pickups` | Sensor | Number of upcoming pickups | `pickups` (list) |
| `sensor.foodsharing_global_statistics` | Sensor | Total weight saved globally (kg) | `recue_missions`, `foodsavers`, `active_fairteiler`, etc. |
| `sensor.foodsharing_user_stats_*` | Sensor | Total rescues by user | `weight_saved_kg`, `rating`, `member_since` |
| `sensor.foodsharing_region_stats_*` | Sensor | Total weight saved in user's region (kg) | `foodsavers`, `corporations`, `fairteiler`, etc. |
| `sensor.foodsharing_buddies_*` | Sensor | Number of buddies | `buddies` (list) |
| `sensor.foodsharing_bananas_*` | Sensor | Number of received bananas (thanks) | `given` |
### Binary Sensors
| Entity | Type | Description |
|--------|------|-------------|
| `binary_sensor.foodsharing_sleeping_hat_*` | Binary Sensor | **On** if the user is currently in "sleeping" mode (vacation). |
### Geo-Location Entities
| Entity | Type | State |
|--------|------|-------|
| `geo_location.basket_*` | Geo-Location | Distance from search center (km) |
| `geo_location.fairteiler_*` | Geo-Location | Distance from search center (km) |
### Calendar
| Entity | Type | Description |
|--------|------|-------------|
| `calendar.foodsharing_pickups` | Calendar | Your scheduled pickup events |
### Buttons
| Entity | Type | Description |
|--------|------|-------------|
| `button.foodsharing__loc__request_basket_` | Button | **Dynamic**: Requests the N-th available basket (Disabled by default). |
| `button.foodsharing__close_basket_` | Button | **Dynamic**: Closes the N-th own active basket (Disabled by default). |
### Services
| Service | Description | Fields |
|---------|-------------|--------|
| `foodsharing.request_basket` | Request a basket by ID | `basket_id` (required), `email` (optional) |
| `foodsharing.close_basket` | Close your own active basket by ID | `basket_id` (required), `email` (optional) |
---
## Basket Sensor Attributes 📦
The basket sensor exposes the full list of baskets as the `baskets` attribute. Each basket in the list contains:
| Key | Description | Example |
|-----|-------------|---------|
| `id` | Basket ID | `123456` |
| `description` | Basket description text | `"Fresh bread and vegetables"` |
| `available_until` | When the basket expires | `"Sun Feb 23 18:00:00 2025"` |
| `picture` | Image URL (or `null`) | `"https://foodsharing.de/images/..."` |
| `latitude` | Basket latitude | `48.1234` |
| `longitude` | Basket longitude | `11.5678` |
| `maps` | Google Maps link | `"https://www.google.com/maps/..."` |
| `keyword_match` | Whether it matches your keywords | `true` / `false` |
---
## Events 🔔
The integration fires custom events that you can use as automation triggers:
| Event | Description | Data |
|-------|-------------|------|
| `foodsharing_keyword_match` | A new basket matches your keywords | Full basket data |
| `foodsharing_new_message` | A new unread message arrived | `conversation_id`, `message` |
| `foodsharing_new_bell` | A new bell notification | Bell data |
| `foodsharing_fairteiler_post` | New post on a fairteiler wall | `fairteiler_id`, `fairteiler_name`, `post` |
---
## HA-Whatsapp Support
> [!TIP]
> This integration works perfectly with the [Home Assistant WhatsApp Integration](https://github.com/FaserF/ha-whatsapp) by the same author!
---
## Automation Examples 🤖
📬 Professional Basket Notification (Telegram/Mobile)
This robust example triggers when the basket count *increases* and handles missing data gracefully. **Note:** For Telegram, the picture link is placed first to ensure it's used for the message preview.
```yaml
automation:
- alias: "Foodsharing: New baskets available"
trigger:
- platform: state
entity_id: sensor.foodsharing_baskets_48_1180_11_6833
condition:
- condition: template
value_template: >
{% set to_state = trigger.to_state.state | int(0) %}
{% set from_state = trigger.from_state.state | int(0) if trigger.from_state is not none else 0 %}
{{ to_state > from_state }}
action:
- service: telegram_bot.send_message
data:
target: !secret telegram_group_id
parse_mode: html
message: |
{% set baskets = state_attr(trigger.entity_id, 'baskets') %}
{% if baskets and baskets | length > 0 %}
{% set b = baskets[0] %}
{% if b.picture %}
🖼️ Preview Image
{% endif %}
🧺 NEW FOOD BASKET {% if b.user_name %}FROM {{ b.user_name | upper | e }} {% endif %}AVAILABLE
Description:
{{ b.description | e }}
{% if b.available_until and b.available_until != 'Unknown' %}
⏰ Available until: {{ b.available_until | e }}
{% endif %}
---
{% if b.maps and b.maps != 'unavailable' and b.latitude and b.longitude %}
📍 Open in Google Maps
{% endif %}
🔗 Open on Foodsharing.de
⚖️ Foodsharing Conduct Rules
{% endif %}
```
🔑 Detailed Keyword Match Notification
Reacts to the `foodsharing_keyword_match` event for instant notifications including all available data.
```yaml
automation:
- alias: "Foodsharing: Keyword match found"
trigger:
- platform: event
event_type: foodsharing_keyword_match
action:
- service: notify.mobile_app_your_phone
data:
title: "🎯 Foodsharing Keyword Match!"
message: >
{% if trigger.event.data.user_name %}From {{ trigger.event.data.user_name }}: {% endif %}{{ trigger.event.data.description }}
{% if trigger.event.data.available_until and trigger.event.data.available_until != 'Unknown' %}
(Until {{ trigger.event.data.available_until }})
{% endif %}
data:
{% if trigger.event.data.picture %}
image: "{{ trigger.event.data.picture }}"
{% endif %}
clickAction: "https://foodsharing.de/essenskoerbe/{{ trigger.event.data.id }}"
```
📋 Detailed basket notification with image
```yaml
automation:
- alias: "Foodsharing: Detailed basket alert"
trigger:
- platform: numeric_state
entity_id: sensor.foodsharing_baskets_48_1180_11_6833
above: 0
action:
- service: notify.mobile_app_your_phone
data:
title: "🧺 Foodsharing Basket Available"
message: >-
{% set baskets = state_attr('sensor.foodsharing_baskets_48_1180_11_6833', 'baskets') %}
{% if baskets | length > 0 %}
{% set b = baskets[0] %}
{{ b.description }}
Available until: {{ b.available_until }}
{% if b.maps != 'unavailable' %}
Maps: {{ b.maps }}
{% endif %}
Link: https://foodsharing.de/essenskoerbe/{{ b.id }}
{% endif %}
data:
image: >-
{% set baskets = state_attr('sensor.foodsharing_baskets_48_1180_11_6833', 'baskets') %}
{% if baskets | length > 0 and baskets[0].picture %}
{{ baskets[0].picture }}
{% endif %}
```
💬 New message notification
```yaml
automation:
- alias: "Foodsharing: New message received"
trigger:
- platform: event
event_type: foodsharing_new_message
action:
- service: notify.mobile_app_your_phone
data:
title: "💬 Foodsharing Message"
message: "You have a new unread message on Foodsharing.de!"
```
🔔 Bell notification
```yaml
automation:
- alias: "Foodsharing: New notification"
trigger:
- platform: numeric_state
entity_id: sensor.foodsharing_notifications
above: 0
action:
- service: notify.mobile_app_your_phone
data:
title: "🔔 Foodsharing"
message: >-
You have {{ states('sensor.foodsharing_notifications') }} unread notification(s).
```
📅 Pickup reminder (1 hour before)
```yaml
automation:
- alias: "Foodsharing: Pickup reminder"
trigger:
- platform: calendar
event: start
offset: "-01:00:00"
entity_id: calendar.foodsharing_pickups
action:
- service: notify.mobile_app_your_phone
data:
title: "📅 Upcoming Pickup"
message: >-
Don't forget your bags! "{{ trigger.calendar_event.summary }}" starts in 1 hour.
```
🏪 Detailed Fairteiler Update
Notifies you about new posts on a Fairteiler wall (e.g., "Fairteiler is full").
```yaml
automation:
- alias: "Foodsharing: Fairteiler status update"
trigger:
- platform: event
event_type: foodsharing_fairteiler_post
action:
- service: telegram_bot.send_message
data:
target: !secret telegram_group_id
parse_mode: html
message: |
📢 NEW ENTRY AT FAIRTEILER
🏫 Location: {{ trigger.event.data.fairteiler_name | e }}
👤 From: {{ (trigger.event.data.post.user_name if trigger.event.data.post.user_name else 'Unknown') | e }}
Message:
{{ trigger.event.data.post.body | e }}
---
🔗 Open Fairteiler on Foodsharing.de
⚖️ Conduct Rules
```
🔧 Request a basket via service call
```yaml
automation:
- alias: "Foodsharing: Auto-request keyword match"
trigger:
- platform: event
event_type: foodsharing_keyword_match
action:
- service: foodsharing.request_basket
data:
basket_id: "{{ trigger.event.data.id }}"
```
---
## Blueprints 📘
A ready-to-use **Pickup Reminder** blueprint is included in the `blueprints/` folder. To install it:
1. Copy `blueprints/automation/foodsharing/pickup_reminder.yaml` to your HA `blueprints/automation/` directory.
2. Go to **Settings → Automations → Blueprints** and configure it.
---
## HA Repairs 🩺
The integration uses Home Assistant's built-in **Repairs** system to notify you of problems:
| Issue | When it appears | What to do |
|-------|----------------|------------|
| **Authentication failed** | Your password was changed or credentials expired | Go to integration options and update email/password |
| **API offline** | Foodsharing.de returns a 503 error | Wait — data resumes automatically when the API recovers |
Repair items appear in **Settings → System → Repairs**.
---
## Bug Reporting 🐛
Open an issue at [GitHub Issues](https://github.com/FaserF/ha-foodsharing/issues). Please include a log with debugging enabled.
To enable debug logging, add this to your `configuration.yaml`:
```yaml
logger:
logs:
custom_components.foodsharing: debug
```
Then find the log at **Settings → System → Logs** → search for `foodsharing` → **Load full logs**.
---
## API Documentation 📖
This integration is built on the **official Foodsharing.de API**. For more information, technical details, or to explore available endpoints for testing, visit the official [Foodsharing DevDocs](https://devdocs.foodsharing.de).
---
## Thanks to 🙏
A huge thanks to the great IT Team from [Foodsharing](https://devdocs.foodsharing.de) for their easy-to-use API and great docs, which made this integration possible!