[Feature]: Add binable.app as an aggregator source (RFC before I open a PR)

[lochmueller]

I propose a feature for:

Sources

Describe your wanted feature

Summary

I'd like to add binable.app as a source — but since it's an aggregator rather than a single municipality, I want to check with you before writing the PR, so we don't end up discussing the concept in a review thread.

What binable is

binable resolves an address to the responsible waste provider, queries that provider, and returns the collection dates in a single normalised JSON format. It's the same idea as the existing platform sources (Recollect, Abfall+, …), except that the platforms behind it are the individual municipal systems — many of which this repository already supports directly.

It is more on the "end user side", because the provider selection is always address based and no need for "internal IDs" or something like that.

The API (verified today)

POST https://binable.app/api/fetch, address as JSON body (also accepted via
X-Address-* headers or query parameters):

{"street": "Im Steinengarten", "houseNumber": "7", "zip": "70567",
 "city": "Stuttgart", "country": "DE"}

Response (abbreviated):

{
  "typeMap": {"paper": "Papiermüll", "bio": "Biomüll", "residualWaste": "Restmüll", "...": "..."},
  "empty": false,
  "provider": {"name": "Stuttgart", "uri": "https://service.stuttgart.de/lhs-services/aws/abfuhrtermine"},
  "paper": {"dates": ["2026-09-17", "2026-10-08"], "next": "2026-09-17", "nextDays": "2", "last": null},
  "bio":   {"dates": ["2026-09-18", "2026-09-25"], "...": "..."}
}

Relevant details:

• Full date lists per waste type, not just next/last — so a real fetch() is possible.
• Waste-type keys are stable camelCase (paper, bio, residualWaste,
  reusableMaterials, glassContainer, christmasTree, toxic, diaper,
  hedgeTreeTrimming, …); typeMap supplies the human-readable labels.
• No account needed, anonymous requests work. An optional API key
  (Authorization: ApiKey ) only raises the rate limit.
• Errors: 422 invalid/missing address field, 404 provider matched but no
  result for that address, 429 rate limit (anonymous: 8 requests per ~7 minutes,
  Retry-After / X-RateLimit-* headers present).
• Coverage is mostly Germany; I verified that at least Switzerland resolves too.

What I'd implement

• source/binable_app.py, args street, house_number, postcode, city,
  country (default DE), optional api_key.
• ICON_MAP keyed on the camelCase API keys using the Icons enum; fetch()
  iterates the response generically, so new waste types the API gains later work
  without a code change.
  SourceArgumentExceptionMultiple for 422/404 (with the API's own message and
  a hint to verify the address on binable.app first), a distinct message for 429.
• Two TEST_CASES only, deliberately — more would trip the anonymous rate limit
  during a test_sources.py run.
• doc/source/binable_app.md with an explicit note at the top: if a direct
  source exists for your municipality, use that one — binable is meant as a
  fallback for addresses that aren't covered yet.

If you'd rather not have an aggregator of this kind in the repository at all,
that's a completely fine answer — I'd just like to know before investing the
implementation time.

Regards,
Tim

[bbr111]

Thanks for asking before implementing this.

I think the important distinction here is that binable is slightly different from our existing shared/platform sources such as ReCollect, Abfall+, C-Trace, etc.

Those are the actual platforms providing the collection data, while binable adds another aggregation layer in between:

WCS -> binable -> provider

instead of:

WCS -> provider/platform

I understand that binable is operated by you, which makes the ownership and contact point clear. Still, from the WCS perspective it would remain an external runtime dependency. If a provider changes its API, it may become less obvious whether a failure originates in WCS, binable, or the provider behind it.

On the other hand, I can definitely see the value as a fallback source. Address-only configuration is very convenient, and it could cover municipalities for which we currently don't have a source.

So I would not consider this a replacement for existing direct/shared-platform sources, but I think it could make sense as an explicitly documented fallback:

prefer an existing direct or shared-platform source where available;

do not remove or deprecate existing sources in favour of binable;

binable would mainly cover addresses/providers which WCS does not currently support.

One thing we should probably discuss before implementation is the anonymous rate limit of 8 requests per ~7 minutes. For normal runtime usage this may be perfectly fine, but we should make sure the source/config flow does not cause unnecessary requests during reloads or reconfiguration.

I would also lean towards keeping the integration anonymous rather than exposing the optional API key unless there is a concrete need for it.

There is also a privacy aspect that should be documented clearly. Using this source means that the user's residential address — street, house number, postal code and city — is sent to binable.app so that it can determine the responsible provider and fetch the collection dates. With a direct source, those address details would instead be sent directly to the local waste provider.

That may be completely acceptable, but users should be made aware of this difference when choosing the source.

Conceptually, with those boundaries, I think this is worth exploring.