{"id":47986735,"url":"https://github.com/szajbergyerek/ha-ship24","last_synced_at":"2026-04-04T11:28:48.760Z","repository":{"id":345274304,"uuid":"1185164441","full_name":"szajbergyerek/ha-ship24","owner":"szajbergyerek","description":"Track your packages for FREE in Home Assistant using the Ship24 API. Supports 1,400+ carriers.","archived":false,"fork":false,"pushed_at":"2026-03-18T21:41:02.000Z","size":56,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-19T01:46:46.141Z","etag":null,"topics":["hacs","hacs-integration","home-assistant","package-tracking","ship24"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/szajbergyerek.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-18T09:55:27.000Z","updated_at":"2026-03-18T21:38:32.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/szajbergyerek/ha-ship24","commit_stats":null,"previous_names":["szajbergyerek/ha-ship24"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/szajbergyerek/ha-ship24","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/szajbergyerek%2Fha-ship24","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/szajbergyerek%2Fha-ship24/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/szajbergyerek%2Fha-ship24/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/szajbergyerek%2Fha-ship24/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/szajbergyerek","download_url":"https://codeload.github.com/szajbergyerek/ha-ship24/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/szajbergyerek%2Fha-ship24/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31397868,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T10:20:44.708Z","status":"ssl_error","status_checked_at":"2026-04-04T10:20:06.846Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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","hacs-integration","home-assistant","package-tracking","ship24"],"created_at":"2026-04-04T11:28:48.641Z","updated_at":"2026-04-04T11:28:48.728Z","avatar_url":"https://github.com/szajbergyerek.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Ship24 Package Tracker for Home Assistant\n\nTrack your packages directly in Home Assistant using the [Ship24](https://ship24.com) API.\nNo polling limits, no subscriptions. Just add your tracking numbers and go.\n\n[![GitHub Release](https://img.shields.io/github/v/release/szajbergyerek/ha-ship24?style=flat-square)](https://github.com/szajbergyerek/ha-ship24/releases)\n[![HACS Custom](https://img.shields.io/badge/HACS-Custom-orange.svg?style=flat-square)](https://github.com/hacs/integration)\n[![CI](https://img.shields.io/github/actions/workflow/status/szajbergyerek/ha-ship24/ci.yaml?label=CI\u0026style=flat-square)](https://github.com/szajbergyerek/ha-ship24/actions/workflows/ci.yaml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](LICENSE)\n\n---\n\n## Features\n\n- Track unlimited packages via Ship24's universal tracking API (supports 1,400+ carriers)\n- Each package becomes its own **sensor entity** with human-readable status\n- **`sensor.ship24_package_summary`**: a single sensor whose state is a complete spoken summary of all packages, ready for voice assistants\n- Sensor attributes: tracking number, courier, last event, last location, ETA, full event history (last 10 events)\n- **Voice assistant ready**: ask Assist, Google Home, or Alexa about your packages without saying a tracking number\n- **Dashboard cards**: works with Entities, Glance, Mushroom, and any custom card\n- **Services** to add and remove packages dynamically from automations\n- **Friendly names**: name your packages (e.g. \"Amazon Order\") for display and voice\n- Polling interval: 1 hour (Ship24 creates a tracker subscription on first query, idempotent)\n\n---\n\n## Free Tier\n\nThe Ship24 free tier API is more than enough for personal use. It covers 1,400+ carriers worldwide, including all major postal services, couriers, and e-commerce platforms. You do not need a paid plan to track your everyday packages at home.\n\nGet your API key at [dashboard.ship24.com/integrations/api-keys](https://dashboard.ship24.com/integrations/api-keys).\n\n---\n\n## Installation via HACS\n\n1. Open HACS in Home Assistant\n2. Go to **Integrations**, click the three-dot menu in the top right corner\n3. Select **Custom repositories**\n4. Add URL: `https://github.com/szajbergyerek/ha-ship24`, set Category to **Integration**\n5. Search for **Ship24** and click **Download**\n6. Restart Home Assistant\n\n---\n\n## Setup\n\n1. Go to **Settings → Devices \u0026 Services → Add Integration**\n2. Search for **Ship24**\n3. Enter your **Ship24 API key**; the setup wizard validates it automatically\n\nA free tier is available at [ship24.com/pricing](https://ship24.com/pricing).\n\n---\n\n## Adding Packages\n\n### Via the Ship24 website\n\nThe easiest way to manage your packages is through the [Ship24 website](https://ship24.com). You can add tracking numbers, set custom names, and monitor statuses there directly. The integration will automatically pick up any trackers associated with your API key on the next poll.\n\n### Via the UI\n\n**Settings → Devices \u0026 Services → Ship24 → Configure**\n\nEnter one package per line. Optionally add a friendly name after a colon:\n\n```\n1Z999AA10123456784:Amazon Order\nRR123456789CN:AliExpress Shoes\nJD014600000000\n```\n\nClick **Submit**. Home Assistant reloads and creates sensor entities for each package.\nThe friendly name appears in the UI and is used by voice assistants instead of the long tracking number.\n\n### Via Service Call\n\nAdd a package from an automation or Developer Tools:\n\n```yaml\nservice: ship24.add_package\ndata:\n  tracking_number: \"1Z999AA10123456784\"\n  friendly_name: \"Amazon Order\"   # optional\n```\n\nRemove a package:\n\n```yaml\nservice: ship24.remove_package\ndata:\n  tracking_number: \"1Z999AA10123456784\"\n```\n\n---\n\n## Voice Assistant\n\n### HA Assist (built-in)\n\nAdd this to your `configuration.yaml` and restart HA:\n\n```yaml\nintent_script:\n  WhereAreMyPackages:\n    speech:\n      text: \"{{ states('sensor.ship24_package_summary') }}\"\n\nconversation:\n  intents:\n    WhereAreMyPackages:\n      - \"where are my packages\"\n      - \"where is my package\"\n      - \"what is the status of my packages\"\n      - \"track my packages\"\n```\n\nExample response:\n\u003e *\"You have 3 packages. Amazon Order is In Transit, last seen in Frankfurt, estimated delivery 2024-03-16. AliExpress Shoes is Delivered. Package JD014... is Pending.\"*\n\n### TTS Morning Briefing\n\n```yaml\nautomation:\n  - alias: \"Morning package briefing\"\n    trigger:\n      - platform: time\n        at: \"08:00:00\"\n    condition:\n      - condition: template\n        value_template: \u003e\n          {{ states('sensor.ship24_package_summary') != 'You have no tracked packages.' }}\n    action:\n      - service: tts.speak\n        data:\n          message: \"{{ states('sensor.ship24_package_summary') }}\"\n```\n\n### Delivery Notification\n\n```yaml\nautomation:\n  - alias: \"Notify on delivery\"\n    trigger:\n      - platform: state\n        entity_id: sensor.amazon_order\n        to: \"Delivered\"\n    action:\n      - service: notify.mobile_app\n        data:\n          message: \u003e\n            {{ state_attr('sensor.amazon_order', 'friendly_name') or 'Your package' }}\n            has been delivered!\n```\n\n---\n\n## Dashboard\n\n### Glance Card\n\n```yaml\ntype: glance\ntitle: Packages\nentities:\n  - entity: sensor.amazon_order\n    name: Amazon\n  - entity: sensor.aliexpress_shoes\n    name: AliExpress\n```\n\n### Entities Card with Summary\n\n```yaml\ntype: entities\ntitle: Package Tracker\nentities:\n  - sensor.ship24_package_summary\n  - sensor.amazon_order\n  - sensor.aliexpress_shoes\n```\n\n### Mushroom Template Card (HACS)\n\n```yaml\ntype: custom:mushroom-template-card\nprimary: \"{{ state_attr('sensor.amazon_order', 'friendly_name') }}\"\nsecondary: \"{{ states('sensor.amazon_order') }}\"\nicon: \u003e\n  {% set s = state_attr('sensor.amazon_order', 'status_code') %}\n  {% if s == 'delivered' %} mdi:package-variant-closed-check\n  {% elif s == 'in_transit' %} mdi:truck-fast\n  {% elif s == 'out_for_delivery' %} mdi:truck-delivery\n  {% else %} mdi:package-variant-closed {% endif %}\nicon_color: \u003e\n  {% if is_state('sensor.amazon_order', 'Delivered') %} green\n  {% elif is_state('sensor.amazon_order', 'In Transit') %} blue\n  {% elif is_state('sensor.amazon_order', 'Exception') %} red\n  {% else %} grey {% endif %}\n```\n\n---\n\n## Sensor Reference\n\n### `sensor.ship24_package_summary`\n\n| Attribute | Example |\n|-----------|---------|\n| **State** | `You have 2 packages. Amazon Order is In Transit...` |\n| `spoken_summary` | Full summary text (no 255-char limit) |\n| `package_count` | `2` |\n\n### Per-package sensor\n\nEach tracked package creates a sensor whose device name equals the friendly name (or tracking number).\n\n| Attribute | Example |\n|-----------|---------|\n| **State** | `In Transit` |\n| `tracking_number` | `1Z999AA10123456784` |\n| `friendly_name` | `Amazon Order` |\n| `status_code` | `in_transit` |\n| `courier` | `ups` |\n| `last_event` | `Departed facility` |\n| `last_event_time` | `2024-03-15T14:30:00.000Z` |\n| `last_location` | `Frankfurt, DE` |\n| `estimated_delivery` | `2024-03-16T00:00:00.000Z` |\n| `origin_country` | `US` |\n| `destination_country` | `DE` |\n| `events` | List of last 10 events |\n\n### Status Values\n\n| Status Code | Display |\n|-------------|---------|\n| `pending` | Pending |\n| `info_received` | Info Received |\n| `in_transit` | In Transit |\n| `out_for_delivery` | Out for Delivery |\n| `failed_attempt` | Failed Delivery Attempt |\n| `available_for_pickup` | Available for Pickup |\n| `delivered` | Delivered |\n| `exception` | Exception |\n| `expired` | Expired |\n\n---\n\n## Requirements\n\n- Home Assistant 2023.1.0+\n- Ship24 API key ([free tier available](https://ship24.com/pricing))\n\n---\n\n## Contributing\n\nPull requests are welcome!\nPlease open an issue first to discuss significant changes.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fszajbergyerek%2Fha-ship24","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fszajbergyerek%2Fha-ship24","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fszajbergyerek%2Fha-ship24/lists"}