Straßenvorschläge beim Tippen
Benötigte Berechtigung:contacts:read(Kontakte lesen)
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.
AuthentifizierungBearer <bm_…>Empfohlen: Authorization: Bearer bm_…. Der Schlüssel wird nur einmal angezeigt; nie in URLs, Logs oder Frontend-Code ablegen.
country?stringLand als ISO-Code. Nur DE liefert Vorschläge; ein Name wie „Deutschland“ geht auch.
q*stringDer getippte Anfang der Straße, gern mit Hausnummer.
city?stringOrtsname, ganz oder als Anfang, geschrieben wie bei GET /api/address/postal.
postalCode?stringPostleitzahl; Leerzeichen zählen nicht.
near?stringPostleitzahl, deren Nähe ohne city die Reihenfolge bestimmt, fünf Ziffern; mit city ohne Wirkung. Eine andere Form ergibt 400 mit context.field = near.
Erfolg.
application/json- response
Straßenvorschläge zu einem getippten Anfang.
attribution?stringNamensnennung, die zu den Vorschlägen gehört: „© OpenStreetMap-Mitwirkende“.
country?stringLand der Anfrage als ISO-Code.
source?stringQuelle 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?booleantrue für DE, sonst false mit leerer Liste.
curl --fail-with-body "https://app.bimetrics.de/api/address/streets?q=string" \ -H "Authorization: Bearer $BIMETRICS_API_KEY"{ "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`.