HKI > HA parcels card

[jonisnet]

Hi Peter,

You already mentioned the HKI Parcels Card (forked and recreated from the HKI-POSTNL-Card by jimz011/hki-elements) as a possible card to use with your integrations. The klaptafel/ha-package-tracker-card is another option.

I noticed that I try to add your repositories as quickly as possible whenever you release updates or new repositories. I have even created automations to notify me when something changes, so I can review it and prepare updates for the card.

Therefore, I would like to suggest making the ha-parcel-card part of your ha-parcel-integrations family. This would keep everything under one roof for users instead of having the different components spread across multiple projects.

Today, I will release version v1.5.0, which includes the latest ha-hermes repository in the card.

The next major version will be v2.0.0 and will contain breaking changes. Older versions of your PostNL repository (versions below 4.x) will no longer be supported. If Arjan Bos does not update his card before then, that card will also be removed from the project.

I also plan to add support for more languages. Currently, the card supports English and Dutch, but I would like to add German, French, Spanish, Portuguese, Norwegian, Swedish, and Danish as starting languages. Support for parcel services from additional countries will also be considered.

The country-specific parcel services will be (partly) automated based on the installed integrations, similar to how this works currently.

Of course, other ideas are very welcome. Please let me know what you think of this idea.

I would also like to invite @klaptafel and @jimz011 to share their thoughts as well. I believe that working together could help us provide the best possible experience for users of all parcel services.

Best regards,
Kees

[peter-mdf]

Hi @jonisnet! Sounds like an interesting plan. I did some research on about 40 carriers and collected information about them in a private repo. I am considering supporting as much as possible, although I need reliable data from people in order to have it all covered. That's currently my biggest issue 😅

I think the current carriers are pretty future rich. At least, I cannot think of new features currently, other then some optimizations perhaps.

I am wondering if cards like yours should depend more on the parcel aggregator or on some other way, which automagically discovers new carriers without the need to make a change within the code. Just not sure how or what. Separate carriers-list repo? I don't know...

I am happy to "adopt" any card within the organization. Rest assured; you can keep making changes to the card as you keep full access rights. My intent is also to give Home Assistant users the best possible experience, since parcels can come from different carriers.

Everyone mentioned is free to share their thoughts :)

[jonisnet]

Hi @peternijssen,

That's an impressive amount of groundwork — 40 carriers is no small feat. Getting reliable data from real users for each one does sound like the hard part.

Fully agree the current carriers are in good shape feature-wise, hard to think of much beyond polish either.

On the auto-discovery question: worth noting hki-parcels-card already does a lightweight version of that today — it auto-detects which installed integrations match the carriers it already knows about, and pre-fills the editor accordingly. True auto-discovery of brand-new carriers without any card-side code change would be a different (and bigger) step, and I don't have a concrete answer for how that should work yet — a shared carriers-list repo, or leaning harder on the Parcel Aggregator's own metadata, both seem worth exploring. Happy to think it through together if useful.

My own goal for the card is to make it as complete as possible — ideally supporting every carrier/integration in one single overview, the way it already tries to today. So in the meantime, could you share the full list of the ~40 carriers you've been researching? I'd like to add all of them to hki-parcels-card for v2.0, so the card is ready as soon as (or before) you roll each one out.

Thanks!

[jimz011]

np @peternijssen I simply asked since the card is integrated in that project (they used to be separate repo's). But not a big deal, I am working on the Android companion anyways 😂

[peter-mdf]

I have a private repo containing research by AI on public endpoints, git repositories etc etc, ranking every carrier. Here is an AI response based upon analyzing all those carriers:

Available now (public, in HACS)

Carrier	Region	Domain	Notes
DHL eCommerce	🇳🇱 NL	dhl_nl	account-based
PostNL	🇳🇱 NL	postnl	account-based (+ MyMail letters)
DPD	🇳🇱 NL	dpd	account-based
GLS	🇳🇱 NL	gls	code-based (number + postcode)
Dragonfly	🇳🇱 NL	dragonfly	code-based
Trunkrs	🇳🇱 NL	trunkrs	code-based
Cainiao	🌍 cross-border	cainiao	code-based
Hermes	🇩🇪 DE	hermes	code-based
Packeta (Zásilkovna)	🇨🇿 🇸🇰 🇭🇺 🇵🇱 🇷🇴	packeta	code-based
Correos	🇪🇸 ES	correos	code-based
Parcel Aggregator	—	parcel_aggregator	combines every installed carrier

Built — not yet released

Carrier	Region	Domain
InPost	🇵🇱 🇮🇹	inpost

On the research roadmap (not built yet)

No integration/domain exists for these yet — listed so the card can pre-stage placeholders. Still reviewing if we can implement these.

DHL Express / Unified 🌍 · USPS 🇺🇸 · Australia Post 🇦🇺 · La Poste 🇫🇷 · Poste Italiane 🇮🇹 · Spring GDS 🌍 · DHL Paket 🇩🇪 · NZ Post 🇳🇿 · PostNord 🇸🇪 🇩🇰 🇳🇴 🇫🇮 · Royal Mail 🇬🇧 · Swiss Post 🇨🇭 · Poczta Polska 🇵🇱 · Sameday 🇷🇴 🇭🇺 🇧🇬 · Econt 🇧🇬 · Quickpac 🇨🇭 · SunYou 🌍 · Bring / Posten 🇳🇴 · Austrian Post 🇦🇹 · An Post 🇮🇪 · Omniva 🇪🇪 🇱🇻 🇱🇹 · CTT 🇵🇹 · Planzer 🇨🇭 · Japan — Japan Post / Yamato / Sagawa 🇯🇵 · Mondial Relay 🇫🇷 🇧🇪 🇳🇱 · FedEx 🌍 · J&T Express 🌏

Evaluated — not currently on the roadmap

Assessed but unlikely to become suite integrations at this point. Contains some challenges I don't know how to solve yet properly.

bpost 🇧🇪 · Evri 🇬🇧 · Yodel 🇬🇧 · Amazon Logistics 🌍 · UPS 🌍 · Aramex 🌍 · SEUR 🇪🇸 · Posti 🇫🇮 · Speedy 🇧🇬 · Colis Privé 🇫🇷 · Correios 🇧🇷 · Canada Post 🇨🇦

[peter-mdf]

Vinted Go is incoming 🤞🏻

[jonisnet]

Card is up to date with Vinted Go v1.5.4

[klaptafel]

I think adding ha-package-tracker-card to the organisation is a great idea. However, the card will not only support ha-parcel-integrations, as I, for example, still use jmdevita/parcel-ha a lot.

And for the card itself; I am considering just supporting just the aggregator instead of supporting each ha-parcel-integration individually. As it should be easier for me (/us?) to maintain instead of supporting and fixing stuff for each carrier integration individually. Especially when that list is growing quite quickly 👀

[klaptafel]

Yeah probably same on my end. But, unless someone can convince me to do otherwise, I think I will just be supporting the aggregator and remove all other individual repo support. Easier and same result (right?). Downside is that users with single carrier (f.e. ha-postnl) will need the aggregator for the card to work.

[klaptafel]

I found a way to keep individual carrier support without any per-carrier maintenance, so I'm no longer planning to drop those in favor of the aggregator only.

Turns out every integration in this org already follows a convention detailed enough to auto-detect directly from the entity itself, no hardcoded per-carrier list needed on my end:

• The sensor's own translation_key is set to one of incoming_parcels, outgoing_parcels, delivered_parcels, outgoing_delivered_parcels. That already tells me which bucket I'm looking at.
• Its parcels attribute is an array where each item carries a carrier field with the display name.

So my card just checks for that shape and reads the carrier name straight off the data. A brand new integration in this org works with zero changes on my end, same promise the aggregator gave me, just without needing it as a middleman.

That also changed my view on the aggregator itself: since it can only relay carriers you already have installed as their own integration, anyone using it already has the direct entity available too, and reading that directly avoids the double counting risk of ever exposing the same parcel through both. So I ended up dropping aggregator support instead of the individual repos, the opposite of what I said above.

So v2.0.0 is in the works 💪🏻

https://github.com/klaptafel/ha-package-tracker-card/releases/tag/v2.0.0

[peter-mdf]

@klaptafel @jonisnet If you are depending on the translation keys, you might have a challenge here. Just had a bug report in which the card from @jonisnet is not working:
ha-parcel-integrations/ha-gls#2 (comment) (Feel free to comment in that issue @jonisnet)

I am trying to follow all best practices from Home Assistant, which led to this challenge. Here is the AI-generated explanation:

Home Assistant integrations that use has_entity_name = True + translation_key (the standard pattern) render the entity's friendly name according to the user's configured HA frontend/instance language — not the integration's own config. ha-gls added a German translation file (de.json) in 1.4.1, which we hadn't shipped before. So any user running HA in German now sees correctly localized German friendly names on all their GLS entities (not just parcels tracked via the new German backend) — this is intentional, standard HA i18n, not a bug or regression in our data/mapping.

If your card matches/filters entities by their translated friendly name (or parses text out of it) rather than by entity_id, unique_id, device_class, or a translation_key-independent attribute, it'll break for any user on a non-English HA locale, for any integration that ships more than one language file — GLS just happens to be the one that recently went from one language to two.

[jonisnet]

Re: the GLS German-locale bug report above — fixed, shipped in v1.7.2: https://github.com/jonisnet/hki-parcels-card/releases/tag/v1.7.2

What changed: the card's entity auto-detection used to guess an entity_id's suffix by trying a fixed list of English/Dutch words (e.g. incoming_parcels / binnenkomende_pakketten), since that suffix follows whatever language HA was displaying when the entity was first created. German was never on that list, so a German-language GLS account (or any carrier's German — or any other untested-language — account) was simply invisible to it.

It now matches against hass.entities[...].translation_key first (grouped by device to figure out which sensors belong to the same account), which is always the plain English key regardless of locale — no more word-list to maintain. The old text-guessing stays as a fallback for older HA cores without that registry cache, so nothing regresses there.

@klaptafel — this ended up being exactly the approach you described in your July 30 comment (matching on the entity's own translation_key/data shape instead of guessing localized text). Good call — turned out to be the right fix once a real non-English case actually broke it.

[klaptafel]

Checked my own matching logic and ha-package-tracker-card is safe from this. Bucket detection uses hass.entities[entityId].translation_key, the entity registry's stable key (e.g. incoming_parcels), never the rendered/translated name. Carrier name comes from the raw parcels[0].carrier attribute value, with a platform-slug fallback, also never friendly_name. So a new locale file on any family integration shouldn't break anything here.

[jimz011]

I am actually working on an Android companion (which is in closed beta testing right now). Your component is used for it @peternijssen. Do you plan to give all carriers the same kind of sensors (as in same naming convention for all carriers?)

This all seems to be working amazingly well. But I also want to support all the carriers you are supporting.

[peter-mdf]

Yes, basically I want to keep all carriers in line with each other, however, some carriers only deliver to your home, some to your home and to service points, others only to service points (or lockers). Some allow you to ship parcels back, some don't.

Basically if you look at DHL and PostNL, I try to keep the sensors they have, in every carrier, as long as they support it.

[jimz011]

I have added support for all of the carriers on your repo in my android app currently.

If I read it well, the aggregator only counts the total parcels and then shows that as a single sensor correct? You'd still need the actual integrations no?

If that is the case then for now I am good 🙃 .

[jonisnet]

Quick progress update, and a thought on the aggregator/auto-discovery idea.

Since July 25: the card now supports 22 carrier integrations (up from Hermes being the newest addition back then) and 19 languages (up from English + Dutch), plus the visual editor picked up per-carrier "add a parcel" support for every account-less carrier. I've also started contributing PHU brand icons upstream to custom-brand-icons for carriers that didn't have a proper logo mark yet, instead of falling back to a generic letter icon.

On the aggregator/auto-discovery question: I wouldn't want auto-discovery to replace the current per-carrier approach — hand-tuning each carrier (its own icon, its own account/postal-code quirks, its own help text) is what makes the card feel tailored rather than generic, and that's worth keeping even though it means more manual work on my end (and yeah, some of the icons I've traced could still use a polish pass).

Where I do think auto-discovery earns its keep is as a bridge for the gap between "you ship a new integration" and "I get around to wiring it into the card properly." The card has actually supported fully manual/generic carrier setup from day one — you can point it at any entity_incoming/entity_delivered pair yourself — so nothing is technically blocked today. It's just extra manual work for the user in the meantime, with none of the nice defaults (icon, colors, translated labels) the "known" carriers get. A small canonical metadata file per integration (even just in each repo's own root, no new aggregator repo needed) could let a card offer a decent default experience for a carrier automatically, the moment it's installed — something like:

{
  "carrier_id": "sameday",
  "display_name": "Sameday",
  "entity_prefix": "sameday",
  "requires_account": false,
  "requires_postal_code": false,
  "supports_outgoing": false,
  "supports_add_parcel": true,
  "locales": ["ro", "en"]
}

That wouldn't stop me from later giving a carrier the full hand-tuned treatment — it would just mean users aren't stuck with zero support (or fully manual setup) in the meantime. Mainly raising it because @klaptafel is weighing a similar aggregator-vs-per-integration tradeoff for ha-package-tracker-card — feels like something worth figuring out together rather than each of us independently building toward the same goal.

[peter-mdf]

Currently there is already a sort of yaml file containing much of that information, as it's being used for the website:
https://github.com/ha-parcel-integrations/ha-parcel-integrations.github.io/blob/main/data/carriers.yml
leads to:
https://ha-parcel-integrations.github.io/carriers/

Doesn't contain everything yet. Also just created a capabilities page based upon all repo's:
https://ha-parcel-integrations.github.io/capabilities/

I could ook into getting all the information together in a yaml/json kinda like file

[peter-mdf]

The discussion here is gone in several directions in the meantime 😅 I think it's good to close it and start separate discussions for whatever topics we still have open.

I am always willing to adopt new repositories to the organization, it only requires them to be onboarded in the whole flow that I have set-up in the meantime for the whole family. For now I won't go beyond supporting existing and new carriers, as a good chunk of my weekly credits go into the research and the support of the current set. However, I can always give write access to any cards within the org.

On the other hand, keeping the cards separated from the org allows it to be independent and support potential other integrations, as I have seen the amount of parcel integrations grow lately. (For example for the Dutch DHL, there are at least 3 other integrations). It's completely up to you guys how you want to move forward, as it's your work :)

If there is a way that I can support you guys with either your (card) development then let me know. Always happy to share info that could help :)