API-Dokumentation

Die Schnittstelle steht ausschließlich Reseller-Vertragspartnern offen. Die Standardlizenz des Shops gestattet ausschließlich die eigene Nutzung; Weitergabe oder Weiterverkauf ist nur mit gesondertem Reseller-Lizenzvertrag zulässig.

Jeder Aufruf trägt den Schlüssel im Header:

curl -H "Authorization: Bearer am_live_..." \
  "https://api.adressmonster.de/v1/count?suchart=gesamt&branchenIds=92"

Ein Schlüssel beginnt mit am_live_ oder — für die Sandbox — mit am_test_. Er wird bei der Erzeugung genau einmal angezeigt und nirgends gespeichert; geht er verloren, hilft nur eine Rotation.

Der wirksame Zugriff ist die Schnittmenge aus den Rechten des Schlüssels und denen des Vertrags. Mögliche Scopes: count:read · records:read · bulk:write · bulk:read · suppressions:read · webhooks:manage · usage:read. Welche für Sie gelten, steht in GET /me.

Basis-URL: https://api.adressmonster.de/v1. Bulk-Exporte, Verbrauchsabruf und Webhooks folgen in späteren Ausbaustufen und stehen bewusst noch nicht in der OpenAPI-Spezifikation — ein generierter Client soll keine Methoden enthalten, die es nicht gibt.

1. Zählen. GET /count liefert Trefferzahl, Feldabdeckung und einen indikativen Preis. Kostenlos und für den hohen Takt einer Suchmaske ausgelegt — Ergebnisse werden zwischengespeichert.

2. Abrufen. GET /records liefert die Datensätze seitenweise. Der erste Aufruf friert die Treffermenge ein; solange Sie den zurückgegebenen nextCursor verwenden, bleibt sie stabil, auch wenn zwischenzeitlich Daten importiert werden.

3. Bereinigen. GET /suppressions nennt Datensätze, die gesperrt oder gelöscht wurden. Regelmäßig abzurufen — dazu verpflichtet der Lizenzvertrag.

Der queryHash ist in Zählung und Abruf identisch. Damit lässt sich belegen, dass beide dieselbe Filtermenge betreffen — nützlich, wenn ein Endkunde eine Rechnung in Frage stellt.

Die geografische Eingrenzung geschieht über suchart:

• gesamt — Bundesweit, ohne geografische Einschraenkung.
• bundesland — Ein oder mehrere Bundeslaender, kommagetrennt. Parameter: bundeslaender
• umkreis — Radius um eine Postleitzahl, 1 bis 500 Kilometer. Parameter: plzumkreis
• plzBereich — Postleitzahlbereiche als VON-BIS-Paare ('76000-76999'), maximal 25 Bereiche. Praefixe wie '76' sind eine Bequemlichkeit der Shop-Oberflaeche und werden hier nicht aufgeloest. Parameter: plzRanges

branchenIds ist Pflicht. Ohne Branchenauswahl lässt sich die Treffermenge nicht vorab abschätzen; eine solche Abfrage würde über den gesamten Bestand laufen und wird deshalb nicht ausgeführt.

Welche Datenarten Sie liefern lassen dürfen, legt Ihr Vertrag fest. Die sieben Kriterien sind: basis · strasse · telefon · email · homepage · ansprechpartner · groesse.

felder=telefon,email lässt die Spalten liefern. hatTelefon=true filtert zusätzlich auf Datensätze, bei denen das Feld gefüllt ist — das verkleinert die Treffermenge und ändert den Preis. Ein Kriterium, das Ihr Vertrag nicht freigibt, führt zu einem Fehler und wird nicht stillschweigend verworfen: Ein Filter ohne Wirkung wäre in Ihrer Oberfläche nicht erklärbar.

Manche Kriterien sind erzwungen. Sie wirken immer, auch wenn Sie sie nicht anfragen, und erscheinen in GET /me mit mode: "forced".

Jeder über diese Schnittstelle ausgelieferte Datensatz trägt eine lieferungsspezifische ID. Das Suffix ist immer exakt 13 Zeichen lang: die Kennung 99999 und eine auf 8 Stellen aufgefüllte Liefernummer.

"id":     "AM87339999900004387"
"baseId": "AM8733"

Basis-ID = id.slice(0, -13)

Speichern Sie die baseId mit. Der Löschkanal nennt Basis-IDs; ohne sie finden Sie Ihre eigenen Datensätze dort nicht wieder, und ein Löschverlangen liefe ins Leere. Der Lizenzvertrag verpflichtet dazu, die Basis-ID mitzuführen und das Wasserzeichen weder zu entfernen noch zu verändern.

GET /suppressions nennt alle Datensätze, die seit Ihrem letzten Abruf gesperrt, deaktiviert oder gelöscht wurden. Sie dürfen nicht mehr genutzt und müssen in Ihren Systemen entfernt werden.

Rufen Sie inkrementell ab: pagination.nextSince der letzten Antwort als since mitgeben. Ohne since beginnt der Feed bei Ihrem Vertragsbeginn — Ihr Erstbestand ist per Definition sauber, weil gesperrte Datensätze nie ausgeliefert werden.

Jede Antwort trägt matchRule: "strip-last-13" — die Regel, mit der sich eine von Ihnen gespeicherte, gewasserzeichnete ID auf die hier genannte Basis-ID zurückführen lässt.

Der Endpunkt ist kostenlos und bleibt auch dann erreichbar, wenn ein Vertrag wegen offener Rechnungen gesperrt ist. Eine Zahlungssperre darf nicht die Betroffenen treffen.

Jede Fehlerantwort hat dieselbe Form. Werten Sie den code aus, nicht den Freitext — der code ist Teil des Vertrags und wird nicht umbenannt, die message kann sich ändern.

{ "error": {
    "code": "criterion_not_permitted",
    "message": "…",
    "requestId": "3f2504e0-4f89-11d3-9a0c-0305e82c3301"
} }

Die requestId steht auch im Header X-Request-Id. Nennen Sie sie in jeder Supportanfrage — damit lässt sich der Vorgang eindeutig finden.

Die konkreten Werte stehen in GET /me unter limits und sind vertraglich vereinbart. Die Mechanik ist immer dieselbe:

• Anfragen je Minute — getrennt für Zählung und Auslieferung. Überschreitung ergibt rate_limited mit Retry-After.
• Zu breite Auswahl — vor der teuren Abfrage abgefangen, selection_too_broad. Grenzen Sie die Branchenauswahl ein.
• Ergebnis zu groß — über maxRecordsPerSyncQuery antwortet /records mit result_too_large. Solche Mengen gehören in einen Bulk-Export.
• Datensätze je Tag und Monat — quota_exceeded. Eine Seite kann auf den verbleibenden Rest gekürzt werden; prüfen Sie pagination.returned, nicht Ihr angefragtes limit.

Eine Seite ist auch dann kürzer als angefragt, wenn ein Datensatz seit dem Einfrieren der Treffermenge gesperrt wurde. Abgerechnet wird immer nur, was tatsächlich geliefert wurde.

Ein Schlüssel mit dem Präfix am_test_ arbeitet gegen einen kleinen, breit gestreuten Ausschnitt echter Firmen. Zählung, Preise, Blättern, Wasserzeichen und Fehlerverhalten sind identisch zur Produktion — nur die Datenmenge ist klein.

Bewusst echte Datensätze statt erfundener: Umlaute, fehlende Hausnummern, null in optionalen Feldern und Ortsnamen wie Schwedt/Oder sind genau die Dinge, an denen eine Anbindung scheitert. Wer dagegen entwickelt, ist beim Umstieg auf am_live_ fertig.

Sandbox-Abrufe werden protokolliert, aber nicht abgerechnet und nicht auf Kontingente angerechnet.