Zum Inhalt

Address Search

Die SmartMaps Address Search API ist eine REST-Schnittstelle zum Abrufen von Adress- und Firmendatensätzen nach Standort. Sie ist die Grundlage für Standortfinder, Händler- und Filialsuchen sowie ähnliche Anwendungsfälle: Ausgehend von einem Standort — einer Adresse, einer Koordinate mit Radius oder einem rechteckigen Kartenausschnitt — und einer optionalen Menge an Kategoriefiltern liefert die API die passenden Adressdatensätze zusammen mit Kontaktdaten, Geo- koordinaten, Entfernungen und Kategorien.

Hauptfunktionen

Drei Wege zur Standortsuche

  • Nach Adresse — Suche über einzelne Adressfelder (Postleitzahl, Stadt, Straße).
  • Nach Position — Umkreissuche um eine GPS-Koordinate.
  • Nach Rechteck — Suche innerhalb einer Bounding Box, z. B. des sichtbaren Kartenausschnitts.

Zusätzlich können Datensätze direkt anhand einer ID abgerufen werden — mehrere anhand ihrer Lieferanten-/Kunden-ID (ByCustomerId, unter Verwendung des ProviderForeignKey aus einem Ergebnis) oder ein einzelner Datensatz anhand seiner internen Kennung (ByIdentifier), zum Beispiel um eine Detailansicht darzustellen.

Kategorie- und Volltextfilter

Jede Suche erfordert mindestens einen Kategoriecode (Branches); die Ergebnisse können zusätzlich mit Freitext-Suchbegriffen (Catchwords) eingegrenzt werden. Die Kategoriecodes sind spezifisch für Ihre Integration und werden bei deren Einrichtung vereinbart — siehe Kategoriecodes in der Referenz.

Einheitliche JSON-Antwort

Alle Endpunkte liefern dasselbe JSON-Objekt — die Hauptteile sind GeoItems (der geokodierte Such- standort), Paging (Paginierung) und AddressItems (die Ergebnisdatensätze), zusammen mit einigen zusätzlichen Containern — sodass derselbe Parsing-Code für jede Variante funktioniert. Das vollständige Schema finden Sie in der API-Referenz.

Erste Schritte

Basis-URL

https://yellowmap.de/api_rst/v2/addresssearch

Autorisierung

Anfragen werden mit HTTP Basic Auth authentifiziert. Das Token wird pro Integration bereitgestellt und bei jeder Anfrage als Authorization-Header gesendet:

Authorization: Basic <TOKEN>

Hinweis

Alle Query-Parameter-Namen sind case-sensitive. Koordinaten verwenden standardmäßig das Format GEODECIMAL_POINT (WGS84 / GPS) mit einem Dezimalpunkt.

Schnellstart

# Search by address
curl -H "Authorization: Basic <TOKEN>" \
  "https://yellowmap.de/api_rst/v2/addresssearch/ByBranchesAndAddress?Branches=<branchcode>&City=Karlsruhe&Zip=76131&IsoCountryCode=DE&Top=50&MaxRadius=50000"

# Radius search around a GPS coordinate (50 km around Karlsruhe)
curl -H "Authorization: Basic <TOKEN>" \
  "https://yellowmap.de/api_rst/v2/addresssearch/ByBranchesAndPosition?Branches=<branchcode>&LocX=8.41876&LocY=49.00923&MaxRadius=50000&Top=50"

# Fetch records by their supplier ID (ProviderForeignKey), several combined with |
curl -H "Authorization: Basic <TOKEN>" \
  "https://yellowmap.de/api_rst/v2/addresssearch/ByCustomerId?CustomerIds=116"

# Combine several category codes (AND-linked, URL-encoded as %26)
curl -H "Authorization: Basic <TOKEN>" \
  "https://yellowmap.de/api_rst/v2/addresssearch/ByBranchesAndAddress?Branches=<base>%26<code1>%26<code2>&City=Karlsruhe&Zip=76131&IsoCountryCode=DE&Top=50&MaxRadius=50000"

Die vollständige Liste der Endpunkte, Parameter und das Antwortschema finden Sie in der API-Referenz.