bimetricsEntwickler
Kontakte

Straßenvorschläge beim Tippen

Als Markdown ansehen

Benötigte Berechtigung:contacts:read(Kontakte lesen)

GET
/api/address/streets

Schlägt für Deutschland bis zu 8 Straßen vor, deren Name so beginnt wie q, mit Ort und Postleitzahlen. Das sind dieselben Daten wie die Vorschläge im Feld „Straße und Hausnummer“ des Kontaktformulars der App. Gesucht wird erst ab drei Buchstaben, darunter bleibt streets leer. Schreibweise wie beim Ort: Groß- und Kleinschreibung und Satzzeichen zählen nicht, „ue“ gilt als „ü“, „Str.“ und „Straße“ gelten gleich. Eine Hausnummer am Ende stört nicht. Mit city grenzt du ein: Meint der Name genau einen Ort, kommen nur dessen Straßen, sonst die aller Orte, die so beginnen („Frankfurt“ trifft Frankfurt am Main und Frankfurt (Oder)). Mit postalCode kommen nur Straßen, die diese Postleitzahl haben. Reihenfolge: ein genau getippter Name vor längeren, dann Straßen in größeren Orten zuerst. Ohne city sortiert near (eine Postleitzahl, in der App die der eigenen Firma) die Straßen aus der Nähe nach vorn: zuerst nach gleichen führenden Ziffern, dann nach dem Abstand der Leitregionen, erst dann nach der Ortsgröße. Die Liste ist nicht vollständig, OpenStreetMap kennt nicht jede Straße, und Hausnummern fehlen ganz. Eine Straße ohne Vorschlag ist deshalb kein Fehler. Für andere Länder kommt supported: false. Ohne q antwortet die Route mit 400 und context.field = q. Quelle: OpenStreetMap (ODbL 1.0). Zeigst du die Vorschläge an, nenne attribution mit Link auf https://www.openstreetmap.org/copyright.

Benötigt einen Schlüssel mit der Berechtigung contacts:read oder read.

Authentifizierung

headerAuthentifizierungBearer <bm_…>

Empfohlen: Authorization: Bearer bm_…. Der Schlüssel wird nur einmal angezeigt; nie in URLs, Logs oder Frontend-Code ablegen.

Query-Parameter

country?string

Land als ISO-Code. Nur DE liefert Vorschläge; ein Name wie „Deutschland“ geht auch.

q*string

Der getippte Anfang der Straße, gern mit Hausnummer.

city?string

Ortsname, ganz oder als Anfang, geschrieben wie bei GET /api/address/postal.

postalCode?string

Postleitzahl; Leerzeichen zählen nicht.

near?string

Postleitzahl, deren Nähe ohne city die Reihenfolge bestimmt, fünf Ziffern; mit city ohne Wirkung. Eine andere Form ergibt 400 mit context.field = near.

Antworten

Erfolg.

application/json
  1. response

Straßenvorschläge zu einem getippten Anfang.

attribution?string

Namensnennung, die zu den Vorschlägen gehört: „© OpenStreetMap-Mitwirkende“.

country?string

Land der Anfrage als ISO-Code.

source?string

Quelle der Liste: osm (OpenStreetMap); fehlt bei anderen Ländern.

streets?array<>|

Bis zu 8 Straßen, der genaue Name zuerst, dann Straßen in größeren Orten; leer unter drei Buchstaben, ohne Treffer oder für andere Länder.

supported?boolean

true für DE, sonst false mit leerer Liste.

Beispielanfrage
curl --fail-with-body "https://app.bimetrics.de/api/address/streets?q=string" \  -H "Authorization: Bearer $BIMETRICS_API_KEY"
Beispielantwort
{  "attribution": "© OpenStreetMap-Mitwirkende",  "country": "DE",  "source": "osm",  "streets": [    {      "city": "Hamburg",      "postalCodes": [        "20095"      ],      "street": "Mönckebergstraße"    }  ],  "supported": true}

Ort aus PLZ, PLZ aus Ort GET

Liefert für Deutschland und Österreich die Orte einer Postleitzahl (`cities`) oder die Orte und Postleitzahlen zu einem Ortsnamen (`places`, `postalCodes`), dieselben Daten wie die Vorschläge im Kontaktformular der App; mit beiden Parametern kommt beides. Den Ortsnamen darfst du so schreiben, wie man ihn tippt: „Muenchen“, „St. Augustin“, „Frankfurt a.M.“ oder nur „Frankfurt“. Trifft der Name genau einen Ort, steht er allein in `places` und seine PLZ zusätzlich in `postalCodes`. Trifft er mehrere, etwa Frankfurt am Main und Frankfurt (Oder), bleibt `postalCodes` leer, und deine Nutzer wählen aus `places`. Ohne Treffer sind beide leer. Gibt es die PLZ nur im anderen der beiden Länder, nennt `elsewhere` dieses Land, etwa Österreich für 4020. Die Listen sind nicht vollständig, Großkunden- und Postfach-PLZ fehlen oft. Eine unbekannte PLZ ist deshalb kein Fehler, die Listen bleiben dann leer. Für andere Länder kommt `supported: false`. Ohne `postalCode` und `city` antwortet die Route mit `400`. Quellen: für Deutschland OpenStreetMap (ODbL 1.0), für Österreich die RTR-GmbH. Zeigst du die Vorschläge an, nenne `attribution`, bei `osm` mit Link auf https://www.openstreetmap.org/copyright. Benötigt einen Schlüssel mit der Berechtigung `contacts:read` oder `read`.

Kontakt anlegen POST

Legt einen Kontakt ohne Bankverbindung und steuerliche Art an; beides lässt sich danach mit updateContact ergänzen. Eine E-Mail-Adresse, die der Versand nicht nehmen würde, lehnt die API mit `400 InvalidContactEmail` ab. Gleiche normalisierte USt-IdNr., externalRef oder gleicher Name ohne Rechtsform ergeben `409 ContactDuplicate` mit existingId. Nur eine Namensdublette kann mit forceDuplicate bestätigt werden. Benötigt einen Schlüssel mit der Berechtigung `contacts:write`.