{"id":18187755,"url":"https://github.com/faserf/ha-keyforsteam","last_synced_at":"2026-04-28T18:05:08.943Z","repository":{"id":260761020,"uuid":"875205301","full_name":"FaserF/ha-keyforsteam","owner":"FaserF","description":"Homeassistant integration to track keyforsteam game prices","archived":false,"fork":false,"pushed_at":"2025-02-20T16:46:34.000Z","size":367,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-20T17:41:17.269Z","etag":null,"topics":["hacs-integration","homeassistant"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/FaserF.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"faserf","custom":"https://paypal.me/FaserF"}},"created_at":"2024-10-19T11:20:29.000Z","updated_at":"2025-02-20T16:46:36.000Z","dependencies_parsed_at":"2024-11-02T12:21:33.594Z","dependency_job_id":"9ba06b24-6565-4687-b315-7a75746adebb","html_url":"https://github.com/FaserF/ha-keyforsteam","commit_stats":{"total_commits":7,"total_committers":1,"mean_commits":7.0,"dds":0.0,"last_synced_commit":"1bbb810d420c8ee991115b0e8e01c175530bd3b3"},"previous_names":["faserf/ha-keyforsteam"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FaserF%2Fha-keyforsteam","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FaserF%2Fha-keyforsteam/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FaserF%2Fha-keyforsteam/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FaserF%2Fha-keyforsteam/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/FaserF","download_url":"https://codeload.github.com/FaserF/ha-keyforsteam/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247666006,"owners_count":20975785,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hacs-integration","homeassistant"],"created_at":"2024-11-03T02:03:10.314Z","updated_at":"2026-04-28T18:05:08.934Z","avatar_url":"https://github.com/FaserF.png","language":"Python","funding_links":["https://github.com/sponsors/faserf","https://paypal.me/FaserF"],"categories":[],"sub_categories":[],"readme":"# KeyForSteam Home Assistant Integration 🔑🎮\n\n[![hacs_badge](https://img.shields.io/badge/HACS-Custom-41BDF5.svg?style=for-the-badge)](https://github.com/hacs/integration)\n[![Ruff](https://github.com/FaserF/ha-keyforsteam/actions/workflows/lint.yaml/badge.svg)](https://github.com/FaserF/ha-keyforsteam/actions/workflows/lint.yaml)\n[![Hassfest](https://github.com/FaserF/ha-keyforsteam/actions/workflows/hassfest.yaml/badge.svg)](https://github.com/FaserF/ha-keyforsteam/actions/workflows/hassfest.yaml)\n\nTrack game prices from **KeyForSteam** (AllKeyShop) directly in Home Assistant. Get real-time updates on the lowest prices, best deals, and seller information for your favorite games.\n\n---\n\n## Features ✨\n\n- **Game Search**: Easily find and add games using the built-in search with autocomplete.\n- **Price Tracking**: Monitor the lowest available price for any game in EUR, USD, or GBP.\n- **Detailed Attributes**: Access seller names, all available offers, product URLs, and ratings.\n- **Additional Sensors**: Separate entities for **Rating**, **Offer Count**, and **Stock Status**.\n- **Manual Refresh**: Use the \"Update Now\" button to trigger an immediate price check.\n- **HA Repairs Service**: Automatic notification if the API changes or data cannot be fetched (24h failure or 404 Not Found).\n- **Diagnostics**: Detailed diagnostic information for easier troubleshooting.\n\n---\n\n## Supported Websites 🌍\n\nThis integration supports all localized versions of the AllKeyShop network. It automatically selects the best site based on your currency:\n\n| Currency | Primary Website | URL |\n|----------|-----------------|-----|\n| **EUR**  | KeyForSteam (DE) | [keyforsteam.de](https://www.keyforsteam.de) |\n| **USD**  | AllKeyShop (US) | [allkeyshop.com](https://www.allkeyshop.com) |\n| **GBP**  | AllKeyShop (UK) | [allkeyshop.com](https://www.allkeyshop.com) |\n\n*Note: The integration uses JSON-LD structured data from these sites to provide stable price tracking.*\n\n---\n\n## Installation 🛠️\n\n### 1. Using HACS (Recommended)\n1. Open **HACS**.\n2. Go to **Integrations**.\n3. Click the three dots in the top right and select **Custom repositories**.\n4. Add `https://github.com/FaserF/ha-keyforsteam` (Category: Integration).\n5. Search for **KeyForSteam** and click **Download**.\n\n### 2. Manual Installation\n1. Download the latest [release](https://github.com/FaserF/ha-keyforsteam/releases/latest).\n2. Copy the `custom_components/keyforsteam` folder to your Home Assistant `\u003cconfig_dir\u003e/custom_components/` directory.\n3. Restart Home Assistant.\n\n---\n\n## Configuration ⚙️\n\n1. Navigate to **Settings** -\u003e **Devices \u0026 Services**.\n2. Click **Add Integration**.\n3. Search for **KeyForSteam**.\n4. **Step 1**: Enter the name of the game (e.g., \"Grand Theft Auto V\").\n5. **Step 2**: Select the correct game from the dropdown and choose your preferred currency.\n\n---\n\n## Entity Details 📊\n\n### Main Sensor (`sensor.keyforsteam_\u003cgame\u003e_price`)\n- **State**: Lowest current price.\n- **Attributes**:\n  - `low_price`: Current cheapest price.\n  - `best_seller`: Name of the store offering the lowest price.\n  - `offer_count`: Total number of stores selling the game.\n  - `rating`: Average user rating of the game.\n  - `top_offers`: List of the top 5 cheapest deals.\n  - `product_url`: Direct link to the price comparison page.\n\n### Rating Sensor (`sensor.keyforsteam_\u003cgame\u003e_rating`)\n- **State**: Average user rating (e.g., 4.5).\n- **Attributes**: `rating_count`.\n\n### Offer Count Sensor (`sensor.keyforsteam_\u003cgame\u003e_offer_count`)\n- **State**: Number of stores selling the game.\n\n### Stock Status (`binary_sensor.keyforsteam_\u003cgame\u003e_stock`)\n- **State**: `on` if at least one offer is available.\n\n### Price Alert (`binary_sensor.keyforsteam_\u003cgame\u003e_price_alert`)\n- **State**: `on` if price is below the threshold set in integration options.\n- **Configuration**: Set the threshold in the integration's **Configure** menu.\n\n### Image Entity (`image.keyforsteam_\u003cgame\u003e_game_image`)\n- **State**: Displays the cover image of the game.\n### Release Calendar (`calendar.keyforsteam_\u003cgame\u003e_calendar`)\n- **State**: Displays upcoming game release dates.\n- **Note**: Standard disabled by default. Can be enabled in entity settings.\n\n### Budget Limit (`number.keyforsteam_\u003cgame\u003e_budget_limit`)\n- **State**: Persistent slider representing your personal budget threshold for purchasing the game.\n\n\n\n### Price Drop Event (`event.keyforsteam_\u003cgame\u003e_price_drop_event`)\n- **Fires**: When the lowest price decreases.\n- **Event Data**: `previous_price`, `current_price`, `difference`.\n\n### Update Button (`button.keyforsteam_\u003cgame\u003e_update`)\n- **Action**: Immediately refresh the game data.\n\n---\n\n## Integration Actions ⚡\n\n### `keyforsteam.get_prices`\nFetch top prices dynamically for any game without requiring persistent sensors.\n- **Arguments**: `game_name` (e.g., `\"Elden Ring\"`)\n- **Returns**: \n  - `game_name`: The catalog match.\n  - `url`: The comparison page URL.\n  - `best_price`: The overall lowest price.\n  - `offers`: List of the top 5 deals.\n\n---\n\n## Assist Sprachsteuerung 🗣️\n\nUm Spielepreise per Sprachbefehl abzufragen, füge folgendes zu deiner `/config/configuration.yaml` hinzu:\n\n```yaml\nintent_script:\n  GetKeyForSteamPrice:\n    speech:\n      text: \"Das Spiel {{ game }} kostet aktuell {{ states('sensor.keyforsteam_' ~ game | lower | replace(' ', '_') ~ '_price') }} Euro.\"\n```\n\nFüge dann in `/config/custom_sentences/de/keyforsteam.yaml` folgendes ein:\n\n```yaml\nlanguage: \"de\"\nintents:\n  GetKeyForSteamPrice:\n    data:\n      - sentences:\n          - \"wie viel kostet {game}\"\n          - \"was kostet {game}\"\n```\n\n\n\n---\n\n## Data Source \u0026 API 🛠️\n\nThis integration uses a combination of two reliable methods to provide up-to-date gaming data:\n\n### 1. Game Search API\nFor the initial search and autocomplete during setup, the integration accesses the **AllKeyShop Catalog API**:\n- **Endpoint**: `https://www.allkeyshop.com/api/v2/vaks.php?action=gameNames`\n- **Data**: A comprehensive list of over 195,000 games with their unique IDs and standard names.\n- **Search Optimization**: The integration uses a custom scoring system to prioritize base games over DLCs and Map Packs.\n\n### 2. Live Price Extraction (JSON-LD)\nTo avoid unstable web scraping and ensure high data accuracy, the integration extracts structured **JSON-LD (Schema.org)** data directly from the product pages:\n- **How it works**: Every product page contains a hidden `\u003cscript type=\"application/ld+json\"\u003e` block that contains the official product metadata (ID, Price, Seller, Availability).\n- **Stability**: This is a standard format used for search engine optimization (SEO), making it much more stable than parsing HTML elements.\n- **Auto-Selection**: The integration automatically chooses the best website based on your configured currency (see [Supported Websites](#supported-websites-🌍)).\n\n---\n\n## Automation Examples 🤖\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e1. Notify when price drops below target\u003c/b\u003e\u003c/summary\u003e\n\n```yaml\nalias: \"Game Price Drop: Call of Duty\"\ntrigger:\n  - platform: state\n    entity_id: binary_sensor.keyforsteam_call_of_duty_black_ops_6_price_alert\n    to: \"on\"\naction:\n  - service: notify.mobile_app_your_phone\n    data:\n      title: \"🔥 Deal Alert: Black Ops 6\"\n      message: \u003e\n        The price for Black Ops 6 has dropped to {{ states('sensor.keyforsteam_call_of_duty_black_ops_6_price') }}€!\n        Cheapest seller: {{ state_attr('sensor.keyforsteam_call_of_duty_black_ops_6_price', 'best_seller') }}\n      data:\n        url: \"{{ state_attr('sensor.keyforsteam_call_of_duty_black_ops_6_price', 'product_url') }}\"\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e2. Daily Price Summary\u003c/b\u003e\u003c/summary\u003e\n\n```yaml\nalias: \"Daily Gaming Deals Summary\"\ntrigger:\n  - platform: time\n    at: \"10:00:00\"\naction:\n  - service: notify.persistent_notification\n    data:\n      title: \"Morning Price Check\"\n      message: \u003e\n        GTA V: {{ states('sensor.keyforsteam_grand_theft_auto_v_price') }}€\n        Elden Ring: {{ states('sensor.keyforsteam_elden_ring_price') }}€\n        Factorio: {{ states('sensor.keyforsteam_factorio_price') }}€\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e3. Change Light Color when a Deal is Active\u003c/b\u003e\u003c/summary\u003e\n\n```yaml\nalias: \"Gaming Deal Visual Alert\"\ntrigger:\n  - platform: state\n    entity_id:\n      - binary_sensor.keyforsteam_game1_price_alert\n      - binary_sensor.keyforsteam_game2_price_alert\n    to: \"on\"\naction:\n  - service: light.turn_on\n    target:\n      entity_id: light.office_desk\n    data:\n      color_name: green\n      brightness: 255\n```\n\u003c/details\u003e\n\n---\n\n## Troubleshooting 🔍\n\nIf the sensor shows \"Unknown\" or hasn't updated in a while:\n1. Enable debug logging in `configuration.yaml`:\n   ```yaml\n   logger:\n     default: info\n     logs:\n       custom_components.keyforsteam: debug\n   ```\n2. Check the logs under **System** -\u003e **Logs**.\n3. If errors persist for 24h, check the **Repairs** section for a known API issue notification.\n\n---\n\n## Contributing 🤝\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n---\n\n## Disclaimer ⚖️\n\nThis integration is not an official product of AllKeyShop or KeyForSteam. It uses publicly available data provided for search engines. Please respect the terms of service of the website.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffaserf%2Fha-keyforsteam","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffaserf%2Fha-keyforsteam","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffaserf%2Fha-keyforsteam/lists"}