Home Assistant integration that provides real-time fuel price data from Tankille API for gas stations across Finland. Monitor fuel prices, set up price alerts, and find the cheapest fuel near you!
- 🚗 Real-time fuel prices for stations across Finland
- 📊 Multiple fuel types (95E10, 98E5, Diesel, Natural Gas, etc.)
- ⛽ Selective fuel type monitoring - Choose which fuel types to track
- 🚫 Gas station chain filtering - Ignore specific chains (Neste, ABC, St1, etc.)
- 📍 Location-based filtering to find stations near you
- 🎯 Station name filtering - Include specific stations by name even if outside radius
- 📱 Smart automation support for price alerts and notifications
- 🔍 Detailed station information including address, coordinates, and last update times
- 📈 Last updated sensors automatically enabled for all stations
- ⚙️ Configurable after setup - Change all settings without recreating the integration
- Home Assistant: 2023.1 or newer
- HACS: Any version
- Python: 3.10+ (handled by Home Assistant)
-
Add Custom Repository:
- Open HACS in your Home Assistant instance
- Go to Integrations → ⋮ (menu) → Custom repositories
- Add URL:
https://github.com/aarooh/hacs-tankille - Category: Integration
- Click Add
-
Install Integration:
- Search for "Tankille" in HACS
- Click Download
- Restart Home Assistant
-
Add Integration:
- Go to Settings → Devices & Services → Add Integration
- Search for "Tankille" and select it
- Download the latest release from the releases page
- Extract and copy the
custom_components/tankilledirectory to your Home Assistant installation'scustom_componentsdirectory - Restart Home Assistant
- Add the integration via Settings → Devices & Services → Add Integration
- Navigate to Integration Setup:
- Settings → Devices & Services → Add Integration
- Search for "Tankille"
- Enter Credentials and Configure Filtering:
- Email: Your Tankille account email
- Password: Your Tankille account password
- Update Interval: How often to check for price updates (default: 60 minutes)
- Location Filtering: Configure latitude, longitude, and search radius
- 🆕 Station Names: Include specific stations by name (even if outside radius)
- 🆕 Ignored Gas Station Chains: Comma-separated list (e.g., "Neste, ABC, St1")
- 🆕 Fuel Types: Select which fuel types to monitor
💡 Pro Tips:
- Always use location filtering to avoid creating hundreds of sensors!
- Use 2-5 km radius in cities, 10-15 km in rural areas
- Add specific stations by name to include favorites outside your radius
- Select only fuel types you actually use to reduce sensor count
You can modify all settings after initial setup:
- Go to Settings → Devices & Services
- Find your Tankille integration
- Click Configure
- Modify any settings (location, station names, ignored chains, fuel types, etc.)
- Integration automatically reloads with new settings
| Fuel Code | Display Name | Default Enabled |
|---|---|---|
95 |
95E10 | ✅ |
98 |
98E5 | ✅ |
98+ |
98 Premium | ❌ |
dsl |
Diesel | ✅ |
dsl+ |
Diesel Premium | ❌ |
ngas |
Natural Gas | ❌ |
bgas |
Biogas | ❌ |
85 |
E85 | ❌ |
hvo |
HVO Diesel | ❌ |
Note: Less common fuel types are disabled by default but can be enabled during setup or in options.
Filter out unwanted gas stations by entering chain names:
Examples:
"Neste"- Filters all Neste stations (Neste, Neste Express, Neste Automat)"ABC, K-Market"- Filters ABC and K-Market stations"Shell, St1, Teboil"- Filters multiple chains"Express"- Filters all Express stations regardless of parent company
How it works:
- Checks station name, brand, and chain fields
- Uses partial matching (substring search)
- Case insensitive matching
- Comma-separated list for multiple chains
Add specific gas stations by name, even if they're outside your location radius:
Examples:
"Shell Vantaa"- Includes any Shell station in Vantaa"Neste Espoo, St1 Tampere"- Includes specific stations in multiple cities"Express, Automat"- Includes all Express and Automat stations regardless of location"Shell Kamppi, ABC Leppävaara, Neste Airport"- Mix of specific station locations
💡 Pro Tip: Check the Tankille mobile application to see the exact station names and brands available in your area. The app shows the same station data that this integration uses, making it easier to find the correct names to include.
How it works:
- Searches through all available stations (not limited by location filter)
- Matches against station name and brand fields
- Uses partial matching (substring search) and case insensitive
- Comma-separated list for multiple stations
- Combines with location filtering: Gets stations within radius PLUS named stations outside radius
- Deduplication: Avoids creating duplicate sensors if a station matches both location and name criteria
Use Cases:
- Include your favorite station that's slightly outside your location radius
- Monitor specific stations along your commute route
- Track prices at stations near your workplace or frequent destinations
- Include a station with consistently good prices even if it's far away
Combined Filtering Example:
- Location Filter: 5km radius around Helsinki city center
- Station Names: "Shell Vantaa, Neste Airport"
- Result: All stations within 5km of Helsinki center + Shell Vantaa + Neste Airport (even if they're outside the 5km radius)
Create a complete fuel monitoring setup with these four complementary cards:
type: vertical-stack
cards:
- type: custom:mushroom-title-card
title: ⛽ Local Fuel Prices
subtitle: Real-time prices from Tankille
- type: entities
title: 95E10 Gasoline Prices
show_header_toggle: false
entities:
- entity: sensor.neste_vantaa_myyrmaki_95e10
name: 🟢 Neste Vantaa Myyrmäki
secondary_info: last-updated
- entity: sensor.st1_helsinki_konala_95e10
name: 🔵 ST1 Helsinki Konala
secondary_info: last-updated
- entity: sensor.abc_s_market_konala_helsinki_95e10
name: 🔴 ABC S-market Konala
secondary_info: last-updated
- entity: sensor.teboil_helsinki_konala_95e10
name: 🟡 Teboil Helsinki Konala
secondary_info: last-updated
state_color: truetype: entities
title: 🏪 Station Details - Neste Vantaa Myyrmäki
show_header_toggle: false
entities:
- entity: sensor.neste_vantaa_myyrmaki_last_updated
name: 🕐 Last Updated
icon: mdi:clock-outline
- type: divider
- entity: sensor.neste_vantaa_myyrmaki_95e10
name: ⛽ 95E10
icon: mdi:gas-station
- entity: sensor.neste_vantaa_myyrmaki_98e5
name: ⛽ 98E5
icon: mdi:gas-station-outline
- entity: sensor.neste_vantaa_myyrmaki_diesel
name: ⛽ Diesel
icon: mdi:truck
- type: divider
- type: attribute
entity: sensor.neste_vantaa_myyrmaki_95e10
attribute: address
name: 📍 Address
- type: attribute
entity: sensor.neste_vantaa_myyrmaki_95e10
attribute: available_fuels
name: ⛽ Available Fuelstype: grid
columns: 2
square: false
cards:
- type: gauge
entity: sensor.neste_vantaa_myyrmaki_95e10
name: Neste Myyrmäki 95E10
min: 1.6
max: 2.2
needle: true
severity:
green: 0
yellow: 1.85
red: 2
- type: gauge
entity: sensor.st1_helsinki_konala_95e10
name: ST1 Konala 95E10
min: 1.6
max: 2.2
needle: true
severity:
green: 0
yellow: 1.85
red: 2type: map
entities:
- entity: sensor.neste_vantaa_myyrmaki_95e10
- entity: sensor.st1_helsinki_konala_95e10
- entity: sensor.abc_s_market_konala_helsinki_95e10
- entity: sensor.teboil_helsinki_konala_95e10
- entity: sensor.gasum_vantaa_kivisto_95e10
- entity: sensor.neste_espoo_karakallio_95e10
- entity: sensor.st1_espoo_leppavaara_diesel
hours_to_show: 24
title: 🗺️ Nearby Fuel Stations
aspect_ratio: "16:9"
theme_mode: autoautomation:
- alias: "⛽ Fuel Price Alert"
description: "Notify when 95E10 drops below €1.80"
trigger:
- platform: numeric_state
entity_id: sensor.neste_vantaa_myyrmaki_95e10
below: 1.80
action:
- service: notify.mobile_app_your_phone
data:
title: "⛽ Cheap Fuel Alert!"
message: "95E10 at Neste Vantaa Myyrmäki is now €{{ states('sensor.neste_vantaa_myyrmaki_95e10') }}/L"- Create Account: If you don't have one, register at tankille.fi
- Mobile App: Ensure you can log in with the same credentials in the Tankille mobile app
- Integration: Use the same email/password in the Home Assistant integration
- Automatic token refresh: No need to re-enter credentials
- Secure storage: Tokens are encrypted and stored locally
- Error recovery: Automatic re-authentication on token expiry
- Debug logging: Enable for troubleshooting authentication issues
Overview of Tankille sensors in Home Assistant showing all fuel price entities
Each fuel price sensor provides:
State: Current fuel price in Euros (€)
Attributes:
station_name: Station name (e.g., "Neste Myyrmäki")brand: Station brand (e.g., "Neste")chain: Station chain (e.g., "Neste Oy")address: Full address stringlatitude/longitude: GPS coordinatesavailable_fuels: List of all fuel types at stationprice_updated: When this fuel price was last updatedprice_reporter: Who reported the pricelast_update_formatted: Human-readable update time
Detailed view of a single fuel price sensor showing all available attributes
Automatically enabled for all stations:
State: Timestamp when station data was last updated
Attributes:
formatted_time: Human-readable timestamptime_ago: Relative time (e.g., "2 hours ago")total_fuel_types: Number of fuel types availableavailable_fuel_types: List of fuel types
Issue: Login fails with correct credentials
# Solutions:
1. Verify credentials work in Tankille mobile app
2. Check Home Assistant logs for specific error
3. Try removing and re-adding the integration
4. Enable debug logging (see below)Issue: "No stations found"
# Solutions:
1. Verify your Tankille account has access to station data
2. Check location filtering settings
3. Try increasing search radius
4. Disable location filtering temporarilyIssue: "Cannot connect to Tankille API"
# Solutions:
1. Check internet connectivity from HA
2. Verify api.tankille.fi is accessible
3. Check for firewall blocking HTTPS requests
4. Review HA network configurationIssue: Missing or outdated prices
# Solutions:
1. Check if data is available in Tankille mobile app
2. Adjust scan interval (minimum 30 minutes recommended)
3. Verify station is still operational
4. Check entity states in Developer ToolsIssue: Stations not being filtered correctly
# Solutions:
1. Check spelling of chain names in ignored list
2. Use partial names (e.g., "Neste" instead of "Neste Express")
3. Check logs for debug messages about filtered stations
4. Verify station names in entity attributesIssue: Station names not being found
# Solutions:
1. Check spelling of station names (partial matching is supported)
2. Try using brand names instead (e.g., "Shell" instead of "Shell Express Kamppi")
3. Use shorter, more generic terms (e.g., "Vantaa" to find all stations in Vantaa)
4. Check debug logs to see what stations were found by name search
5. Verify station exists in Tankille database via their mobile app
6. **💡 Use the Tankille mobile app to browse available stations and copy exact names**Issue: Too many stations being included by name search
# Solutions:
1. Use more specific search terms (e.g., "Shell Kamppi" instead of "Shell")
2. Use exact location names (e.g., "Neste Vantaa Myyrmäki" instead of "Neste")
3. Combine with ignored chains to filter out unwanted results
4. Check entity registry to disable unwanted sensors manuallyIssue: Too many fuel type sensors
# Solutions:
1. Reconfigure integration and select fewer fuel types
2. Disable unwanted sensors in entity registry
3. Use ignored chains to filter out unwanted stations
4. Be more specific with station names to reduce station countAdd to your configuration.yaml:
logger:
default: info
logs:
custom_components.tankille: debug
custom_components.tankille.tankille_client: debug-
Check Entity Registry:
- Developer Tools → States
- Filter by
sensor.and search for your station names
-
Review Integration Logs:
- Settings → System → Logs
- Search for "tankille"
-
Test API Connectivity:
# From HA container/host curl -I https://api.tankille.fi
Contributions are welcome! Here's how you can help:
- 🐛 Report Bugs: Use the issue tracker
- 💡 Suggest Features: Open a feature request issue
- 🔧 Submit PRs: Fork, create feature branch, submit pull request
- 📖 Improve Docs: Help improve documentation and examples
# Clone repository
git clone https://github.com/aarooh/hacs-tankille.git
# Create development environment
cd hacs-tankille
python -m venv .venv
source .venv/bin/activate # Linux/Mac
# For Windows:
# In Command Prompt (cmd.exe): .venv\Scripts\activate.bat
# In PowerShell: .venv\Scripts\Activate.ps1
# In Git Bash / MinGW: source .venv/Scripts/activate
# Install dependencies
pip install -r requirements.txtManually updating to homeassistant.
cd /config/custom_components/
# Remove the incorrectly placed directory
rm -rf tankille
# Clone and move files correctly
git clone https://github.com/aarooh/hacs-tankille.git temp_tankille
mv temp_tankille/custom_components/tankille ./tankille
rm -rf temp_tankille- 📈 Price trend analysis (7-day, 30-day changes)
- 🗺️ Route-based recommendations
- 🎯 Advanced price alerts with trend analysis
- 📊 Enhanced dashboard cards with charts
- 🤖 Predictive analytics for price forecasting
This project is licensed under the MIT License - see the LICENSE file for details.
- Tankille Team: For providing the fuel price API
- Home Assistant Community: For integration development guidance
- HACS: For making custom integrations easily accessible
- Contributors: Everyone who has helped improve this integration
- 🐛 Issues: GitHub Issues
- 💬 Discussions: GitHub Discussions
- 📖 Documentation: Integration Docs
- 🏠 Home Assistant: Community Forum
- Station Names Filtering: Include specific stations by name even if outside location radius
- Search through all available stations using partial name matching
- Combine with location filtering for comprehensive station selection
- Support for comma-separated list of station names or brands
- Perfect for including favorite stations outside your normal radius
- Fuel Type Selection: Choose specific fuel types during setup and in options
- Multi-select UI with checkboxes for all available fuel types
- Defaults to most common types (95E10, 98E5, Diesel, E85)
- Only creates sensors for selected fuel types
- Enhanced Gas Station Chain Filtering:
- Now filters by station name, brand, and chain fields
- Uses intelligent partial matching (e.g., "Neste" matches "Neste Express")
- More intuitive filtering based on what users actually see
- Complete Options Flow:
- Modify ALL settings after initial setup without recreating integration
- Change location, station names, ignored chains, fuel types, scan interval, etc.
- Integration automatically reloads when settings change
- Better User Experience: Clear descriptions and examples in configuration UI
- Reduced Sensor Count: Fuel type filtering prevents creation of unwanted sensors
- Smarter Filtering Logic: Modular
is_station_ignored()function with comprehensive matching - Enhanced Logging: Better debug information for troubleshooting filtering issues
- Backward Compatibility: Existing setups continue working with sensible defaults
- Improved handling of empty or invalid filter configurations
- Better error handling in options flow validation
- Updated README with detailed filtering examples
- Added troubleshooting section for filtering issues
- Real-time fuel price monitoring from Tankille API
- Location-based station filtering
- Multiple fuel type support
- Last updated sensors for all stations
- Comprehensive station information and attributes
- Authentication with token refresh
- HACS integration support
⭐ If this integration is helpful, please consider giving it a star on GitHub! ⭐