Zum Inhalt

Address Search API-Referenz

Die SmartMaps Address Search API bietet eine REST-Schnittstelle für die geografische Unternehmens-/Adresssuche. Sie stellt fünf Endpunkte bereit: drei Suchendpunkte, die sich nur darin unterscheiden, wie der Suchstandort angegeben wird, einen Endpunkt zum Abrufen von Datensätzen anhand ihrer Lieferanten-/Kunden-ID und einen Endpunkt zum Abrufen eines einzelnen Datensatzes anhand seiner internen Kennung.

Basis-URL

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

Autorisierung

Die Authentifizierung erfolgt über HTTP Basic Auth. Das Token wird pro Integration von YellowMap bereitgestellt und bei jeder Anfrage als Authorization-Header gesendet:

Authorization: Basic <TOKEN>

<TOKEN> ist die Base64-kodierte Kombination aus Partnername und dem von YellowMap ausgestellten Access Key — also base64("<SystemPartner>:<SecurityID>"). (Die apiKey-artige Query-Authentifizierung, die von einigen anderen SmartMaps-APIs verwendet wird, wird hier nicht akzeptiert — Anfragen ohne den Basic-Header werden mit 401 Unauthorized beantwortet.)

curl -H "Authorization: Basic <TOKEN>" \
  "https://yellowmap.de/api_rst/v2/addresssearch/ByBranchesAndAddress?Branches=<branchcode>&City=Karlsruhe"

Hinweis

Bei allen Namen von Query-Parametern wird zwischen Groß- und Kleinschreibung unterschieden.

Endpunkte

Suche nach Adresse

GET /addresssearch/ByBranchesAndAddress

Suche anhand einzelner Adressfelder (Postleitzahl, Stadt, Straße).

Parameter Erforderlich Standardwert
Branches Ja
Channel Nein empty
IsoCountryCode Nein DE
IsoLocale Nein de-DE
Zip Nein
City Nein
Street Nein
MaxRadius Nein -1 (unlimited, max. 300 km)
Top Nein 20
OrderBy Nein MATRIX_COMPANY_NAME
Page Nein 1
FreeFilter Nein empty
Addition Nein empty
curl -H "Authorization: Basic <TOKEN>" \
  "https://yellowmap.de/api_rst/v2/addresssearch/ByBranchesAndAddress?Branches=<branchcode>&City=Karlsruhe&Zip=76131&Street=CAS-Weg%201&IsoCountryCode=DE&Top=50&MaxRadius=50000"

Suche nach Position

GET /addresssearch/ByBranchesAndPosition

Umkreissuche ausgehend von einer GPS-Koordinate.

Parameter Erforderlich Standardwert
Branches Ja
Channel Nein empty
IsoCountryCode Nein DE
IsoLocale Nein de-DE
LocX Ja
LocY Ja
CoordFormatIn Nein GEODECIMAL_POINT
MaxRadius Nein -1
Top Nein 20
OrderBy Nein MATRIX_COMPANY_NAME
Page Nein 1
FreeFilter Nein empty
Addition Nein empty
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"

Suche nach Rechteck (Bounding Box)

GET /addresssearch/ByBranchesAndRectangle

Suche innerhalb eines Rechtecks, z. B. des sichtbaren Kartenausschnitts.

Parameter Erforderlich Standardwert
Branches Ja
Channel Nein empty
IsoCountryCode Nein DE
IsoLocale Nein de-DE
Lux Ja
Luy Ja
Rlx Ja
Rly Ja
CoordFormatIn Nein GEODECIMAL_POINT
Top Nein 20
OrderBy Nein MATRIX_COMPANY_NAME
Page Nein 1
FreeFilter Nein empty
Addition Nein empty

Lux/Luy = obere linke Ecke, Rlx/Rly = untere rechte Ecke des Rechtecks.

curl -H "Authorization: Basic <TOKEN>" \
  "https://yellowmap.de/api_rst/v2/addresssearch/ByBranchesAndRectangle?Branches=<branchcode>&Lux=8.3&Luy=49.1&Rlx=8.5&Rly=48.9&Top=50"

Datensätze anhand der Kunden-/Provider-ID abrufen

GET /addresssearch/ByCustomerId

Ruft Adressdatensätze anhand ihres bzw. ihrer Lieferanten-Fremdschlüssel ab — dem Wert ProviderForeignKey aus den Identifiers eines Suchergebnisses. Nützlich, um bestimmte Datensätze, die Sie anhand ihrer Provider-ID gespeichert haben, erneut abzurufen.

Parameter Erforderlich Standardwert
CustomerIds Ja

Übergeben Sie eine oder mehrere ProviderForeignKey-IDs; kombinieren Sie mehrere mit |.

curl -H "Authorization: Basic <TOKEN>" \
  "https://yellowmap.de/api_rst/v2/addresssearch/ByCustomerId?CustomerIds=116"

Die Antwort verwendet dieselbe Antwortstruktur wie die Suchendpunkte.

Einzelnen Datensatz anhand der Kennung abrufen

GET /addresssearch/ByIdentifier

Ruft einen einzelnen Datensatz anhand seiner Kennung (YMID) ab, z. B. für eine Detailansicht.

Parameter Erforderlich Standardwert
Identifier Ja

Der Wert von Identifier ist das Feld YMID aus einer Suchantwort und muss URL-kodiert sein (z. B. kann YMIDUrlEncoded aus der Suchantwort direkt verwendet werden).

curl -H "Authorization: Basic <TOKEN>" \
  "https://yellowmap.de/api_rst/v2/addresssearch/ByIdentifier?Identifier=<ymid-url-encoded>"

Die Antwort verwendet dieselbe Antwortstruktur wie die Suchendpunkte, enthält jedoch immer genau einen Treffer (Paging.MaxCount: 1).

Parameterreferenz

Logging

Die Authentifizierung erfolgt über den HTTP-Basic-Auth-Header (siehe Autorisierung).

Name Typ Standardwert Beschreibung
Channel string empty Optionaler Query-Parameter für clientseitiges Logging

Inhalt

Name Typ Standardwert Beschreibung
Branches string — (required) Kategoriecodes (spezifisch für Ihre Integration — siehe Kategoriecodes). Mindestens ein Code ist erforderlich; eine Anfrage ohne Branches liefert 400 ("Eine oder mehrere Branchen sind erforderlich."). Kombinieren Sie Codes mit \| (ODER) und %26 (UND, URL-kodiertes &). Hinweis: \| bindet stärker als &, sodass <a>&<b>\|<c> als <a>&(<b>\|<c>) interpretiert wird.
Catchwords string Zusätzlicher Freitextfilter zusätzlich zu Branches, Begriffe durch Leerzeichen getrennt, z. B. itservices computer support. (Kein eigenständiger Suchmodus — Branches ist weiterhin erforderlich.)

Standort

Name Typ Standardwert Beschreibung
IsoCountryCode string DE ISO-Ländercode (die API akzeptiert auch die einbuchstabige Form, z. B. D, und ist bei diesem Wert für adressbasierte Suchen tolerant)
IsoLocale string de-DE Spracheinstellung für mehrsprachige Inhalte
Location string Standortsuche in einem einzigen Feld — Straße, Postleitzahl und Stadt können zusammen in einem Feld übergeben werden
LocX float Längengrad, z. B. 8.41876
LocY float Breitengrad, z. B. 49.00923
Lux, Luy float Koordinaten der oberen linken Ecke (Rechtecksuche)
Rlx, Rly float Koordinaten der unteren rechten Ecke (Rechtecksuche)
CoordFormatIn string GEODECIMAL_POINT Koordinatenformat. GEODECIMAL_POINT steht für WGS84 / GPS. Alternativen sind u. a. MERCATOR.
Zip string Postleitzahl. Kann unvollständig sein, wenn sie allein angegeben wird (761). Mehrere mit \| trennen (76133\|08269); dann muss jede vollständig sein.
Street string Straße einschließlich Hausnummer
City string Stadt

Ergebnissteuerung

Name Typ Standardwert Beschreibung
MaxRadius int -1 Suchradius in Metern. -1 bedeutet unbegrenzt (max. 300 km).
Top uint 20 Maximale Anzahl der Ergebnisse pro Seite
Page uint 1 Seitenzahl für die Paginierung
OrderBy string MATRIX_COMPANY_NAME Sortierung der Ergebnisse. Zulässige Werte: COMPANY_NAME, DISTANCE, MATRIX_COMPANY_NAME, MATRIX_DISTANCE, PHONE_BOOK_SEARCH_DISTANCE_NAME, PHONE_BOOK_SEARCH_NAME, EVENT_START_DATE, EVENT_START_DATE_DISTANCE, EVENT_DISTANCE, NONE.

Kennung

Name Typ Standardwert Beschreibung
CustomerIds string Lieferanten-Fremdschlüssel — der Wert ProviderForeignKey aus einem Suchergebnis. Mehrere mit \| kombinieren. Verwendet von ByCustomerId.
Identifier string Interner Primärschlüssel (verschlüsselt) — die YMID aus einer Suchantwort. Verwendet von ByIdentifier.

Erweitert

Name Typ Standardwert Beschreibung
FreeFilter string empty Spezialfilter für kundenspezifische Lösungen
Addition string empty Zusätzliche key=value-Paare für kundenspezifische Lösungen — siehe Addition-Parameter

Addition-Parameter

Addition enthält eigene key=value-Paare. Der häufigste Anwendungsfall ist ein Referenzpunkt für die Entfernungsberechnung:

Schlüssel Beschreibung
LocXForDistanceCalculation Längengrad des Referenzpunkts, von dem aus gemessen wird
LocYForDistanceCalculation Breitengrad des Referenzpunkts

Sind beide gesetzt, enthält jeder Treffer BasicData.Geo.Distance — die Luftlinienentfernung zu diesem Punkt in Metern. Ohne sie bleibt das Feld leer.

Trennzeichen innerhalb von Addition kodieren

Da Addition eigene Trennzeichen enthält, müssen diese URL-kodiert werden: = wird zu %3D, & wird zu %26. Unkodiert werden die Paare als normale Query-Parameter gelesen und die Entfernung wird nicht berechnet.

&Addition=LocXForDistanceCalculation%3D8.47029%26LocYForDistanceCalculation%3D49.00129

Einen vollständigen Aufruf zeigt Filialsuche über Kartenausschnitt.

Antwortstruktur

Alle Endpunkte (Suche, ByCustomerId und ByIdentifier) liefern dasselbe JSON-Objekt. Die drei Hauptbestandteile sind GeoItems, Paging und AddressItems; die Antwort enthält außerdem mehrere zusätzliche Container (meist leere Arrays, sofern für die Anfrage/Daten nicht relevant) sowie einige Statusfelder:

{
  "GeoItems":     [ ... ],   // geocoding of the search location
  "Paging":       { ... },   // pagination
  "AddressItems": [ ... ],   // result records

  "AddressShadowItems": [],  // shadow / duplicate entries
  "AddressesNearby":    [],  // further locations nearby
  "AddressTiles":       [],  // tile information
  "RegioAdItems":       [],  // regional ad entries
  "RelatedBranches":    [],  // related categories
  "SeparatedBranches":  [],  // separated categories

  "SearchData":            { ... },  // the parameters/location used for the search
  "AddressItemsCopyright": { "Text": "YellowMap AG", "BrandingList": [] },

  // status / diagnostics
  "IsRequestAuthenticated": true,    // authentication / access flags
  "IsAccessApproved": true,
  "StatusCode": 0,                   // 0 = ok; non-zero indicates a problem (see PublicReport)
  "Exceptions": [],
  "PublicReport": "",                // user-facing error text when something went wrong
  "InternalError": null
}

GeoItems[] — Geocoding des Suchstandorts

Feld Typ Beschreibung
Country string Länderkürzel (D)
District string Bundesland / Region
Zip string Postleitzahl
City string Stadt
CityAddOn string? Zusatz zum Stadtnamen
CityPart string? Stadtteil
Street string Straße
HouseNo string? Hausnummer
GeoLevel string? Granularität, auf die der Standort aufgelöst wurde
CityLevel string? Granularität des Stadt-Treffers
DistrictID string? Interne Bezirks-Kennung
SeoLink string? SEO-freundliches Link-Fragment für den Standort
Description string? Menschenlesbare Beschreibung des Standorts
LocX string Längengrad des Suchstandorts
LocY string Breitengrad des Suchstandorts
CoordFormat string Koordinatenformat (z. B. GEODECIMAL_POINT)

Paging — Paginierung

Feld Typ Beschreibung
Page int Aktuelle Seite
MaxPage int Letzte verfügbare Seite
Count int Anzahl der Ergebnisse auf der aktuellen Seite
MaxCount int Gesamtzahl der Treffer

AddressItems[] — Ergebnisdatensätze

Jedes Element in AddressItems steht für einen Treffer (einen Händler, eine Filiale, ein Geschäft usw.). Die Kerndaten befinden sich in BasicData; daneben verfügt jedes Element außerdem über Comments, AdditionalContacts, HotelReservationData, ImmoData, History und Similarity (siehe Weitere Felder je AddressItem weiter unten).

BasicData enthält: Identifiers, Address, Contact, Geo, BranchListElements, Marketing, BusinessData, AdditionalInfo, MemoItems, Images, ObjectListItems, ReleaseManagement und Copyright. Die wichtigsten davon:

BasicData.Identifiers

Feld Typ Beschreibung
YMID string Interne ID (Base64-kodiert, verschlüsselt)
YMID3 string Kurzform der ID
YMIDUrlEncoded string URL-kodierte Variante der YMID — diese direkt an ByIdentifier übergeben
YMIDPathEncoded string Pfad-sichere Variante der YMID
YMIDDecoded string Numerische Klartext-ID
ProviderID string ID des Datenlieferanten
ProviderForeignKey string Fremdschlüssel des Lieferanten für den Datensatz
ProviderEnum string Kurzname des Datenlieferanten

BasicData.Address

Feld Typ Beschreibung
CompanyName string Firmenname
CompanyNameAddon1..3 string? Zusätze zum Firmennamen
FirstName string? Vorname (bei Personeneinträgen)
Country string Länderkürzel
Zip string Postleitzahl
City string Stadt
CityPart string Stadtteil
Street string Straße einschließlich Hausnummer
HouseNo string? Hausnummer (separates Feld, sofern vorhanden)
Postbox string? Postfach

BasicData.Contact

Feld Typ Beschreibung
Phone string Telefonnummer
Mobile string Mobilnummer
Fax string Faxnummer
Email string E-Mail-Adresse
Url string Website
Url2, Url3 string? Weitere Websites

BasicData.Geo

Feld Typ Beschreibung
XCoord string Längengrad des Ergebnisses
YCoord string Breitengrad des Ergebnisses
GeocodeStatus string? Status des Geocodings
Distance string Luftlinienentfernung zum Suchstandort in Metern
MatrixRouteDistance string Routenentfernung in Metern
MatrixRouteTime string Geschätzte Fahrzeit in Sekunden
DistanceToRoute string? Entfernung zur Route (bei routenbasierten Suchen)

BasicData.BranchListElements[]

Feld Typ Beschreibung
BranchCode string Kategoriecode
BranchText string Klartext-Kategoriename
Keywords string? Mit der Kategorie verknüpfte Schlagwörter
SortNr int Sortierreihenfolge
Kategorie int Kategorie-Klassenindikator
BranchCodePredecessor string? Vorgängercode, falls der Code abgelöst wurde
NoOfBranchCodeChilds int Anzahl der untergeordneten Kategorien
Frequency, MarketPlace, MarketNumber, Country, Language string? / null Zusätzliche, oft leere Klassifizierungsfelder

BasicData.Marketing

Feld Typ Beschreibung
DisplayType string Anzeigetyp (0 = Standard)
TypeEnumValue string Eintragstyp (BASIC usw.)
TypeValueVisible string Anzeigebezeichnung für den Eintragstyp
IsCharged bool Kennzeichen für kostenpflichtige Einträge

BasicData.BusinessData

Feld Typ Beschreibung
BusinessID string Unternehmens-ID (verschlüsselt)
BusinessIDDecoded string Klartext-Unternehmens-ID
AddressID string? Interne Adress-ID
IsCompany bool Kennzeichen für Unternehmenseinträge
HandelsregisterType string? Art des Handelsregistereintrags
HandelsregisterNr string? Handelsregisternummer
UStIdNr string? Umsatzsteuer-Identifikationsnummer
DateLastChange string Datum der letzten Änderung (yyyy-MM-dd HH:mm:ss.fff)
DateLastCheck string Datum der letzten Prüfung

BasicData.AdditionalInfo

Feld Typ Beschreibung
Rating string Bewertung (numerisch)
RatingCount string Anzahl der Bewertungen
RatingCategories array Bewertungen je Kategorie
Turnover string Umsatzklasse
CompanySize string Unternehmensgröße
BusinessImage object? Bild/Logo des Unternehmens
BusinessNews string News-/Ankündigungstext
CompanyInfo string Freitextbeschreibung des Unternehmens

BasicData.MemoItems[] und BasicData.Images[]

MemoItems enthält strukturierte Vermerke zum Datensatz — insbesondere Öffnungszeiten (der Legacy-Webservice AddressSearch verwendet Pipe-getrennte Werte mit Mask-Typen NONE, MASK_1MASK_5). Images enthält Bilder/Logos. Beide sind je nach Datensatz häufig leere Arrays.

Hinweis

Das genaue Feldlayout von MemoItems / Images (sowie von ObjectListItems / ReleaseManagement) hängt vom Datensatz ab und sollte am besten anhand eines Datensatzes überprüft werden, der tatsächlich Öffnungszeiten oder Bilder enthält.

Weitere Felder je AddressItem

Feld Typ Beschreibung
Comments array Kommentare zum Eintrag
AdditionalContacts array Zusätzliche Kontaktdaten
HotelReservationData object? Reservierungsdaten (kategoriespezifisch)
ImmoData array Immobiliendaten (kategoriespezifisch)
History.IsHistorical bool Kennzeichen für historische Einträge
History.ChangeDate string Datum der letzten Änderung
History.ChangeType string Art der Änderung (NONE usw.)
History.ReasonType string Grund für die Änderung (NONE usw.)
Similarity object? Informationen zur Ähnlichkeit

Beispielantwort (gekürzt)

{
  "GeoItems": [
    {
      "Country": "D",
      "District": "Baden-Württemberg",
      "Zip": "76131",
      "City": "Karlsruhe",
      "Street": "CAS-Weg",
      "HouseNo": "1",
      "LocX": "8.41876",
      "LocY": "49.00923",
      "CoordFormat": "GEODECIMAL_POINT"
    }
  ],
  "Paging": { "Page": 1, "MaxPage": 1, "Count": 50, "MaxCount": 59 },
  "AddressItems": [
    {
      "BasicData": {
        "Identifiers": {
          "YMID": "<ymid>",
          "YMIDUrlEncoded": "<ymid-url-encoded>",
          "YMIDDecoded": "<numeric-id>",
          "ProviderEnum": "EXAMPLE_PROVIDER"
        },
        "BranchListElements": [
          { "BranchCode": "<branchcode>", "BranchText": "Example category" }
        ],
        "Address": {
          "CompanyName": "Example Company GmbH",
          "Country": "D",
          "Zip": "76131",
          "City": "Karlsruhe",
          "Street": "Example Street 1a"
        },
        "Contact": { "Phone": "+49 721 0000000", "Email": "info@example.com", "Url": "https://www.example.com" },
        "Geo": { "XCoord": "8.44701", "YCoord": "48.9912", "Distance": "2428", "MatrixRouteDistance": null, "MatrixRouteTime": null },
        "Marketing": { "DisplayType": "0", "TypeEnumValue": "BASIC", "IsCharged": false },
        "MemoItems": [],
        "Images": []
      },
      "Comments": [],
      "AdditionalContacts": [],
      "History": { "IsHistorical": false, "ChangeType": "NONE", "ReasonType": "NONE" }
    }
  ],
  "AddressShadowItems": [], "AddressesNearby": [], "AddressTiles": [], "RegioAdItems": [],
  "RelatedBranches": [], "SeparatedBranches": [],
  "SearchData": { "Branches": "<branchcode>", "Catchwords": "", "Location": { "XCoord": "8.41876", "YCoord": "49.00923" } },
  "AddressItemsCopyright": { "Text": "YellowMap AG", "BrandingList": [] },
  "StatusCode": 0, "Exceptions": [], "PublicReport": "", "InternalError": null
}

Kategoriecodes

Der Parameter Branches erwartet Kategoriecodes, die spezifisch für Ihre Integration sind. Es gibt keine generische, öffentliche Liste von Codes — die für Ihre Daten verfügbaren Codes (sowie, sofern zutreffend, ein Basiscode für das gesamte Sortiment) werden bei der Einrichtung der Integration festgelegt. Weitere Codes können auf Anfrage aktiviert werden.

Kombinieren von Kategoriecodes

Ein einzelner Code (Branches=<branchcode>) genügt; mehrere Codes werden mit & UND-verknüpft und müssen im Query-String URL-kodiert als %26 übergeben werden. Einige Integrationen erwarten außerdem, dass ein Basiscode für das gesamte Sortiment enthalten ist — dies ist Teil der Integrationskonfiguration.

Branches=<base>%26<code1>%26<code2>%26<code3>

Aufgelöst: <base> & <code1> & <code2> & <code3>

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"

Fehler

  • Fehlender Authorization-Header → 401 Unauthorized mit dem Body "Access to the system has been denied. Basic authentication header missing."
  • Fehlende erforderliche Parameter → 400 Bad Request mit einer einfachen JSON-String-Meldung, z. B. "Eine oder mehrere Branchen sind erforderlich." (kein Branches) oder "Die Angabe des X-Wertes der Standortkoordinate ist nicht korrekt. …" (fehlende/ungültige Koordinaten).
  • Andere serverseitige Probleme werden als 200 OK mit einer leeren Ergebnismenge und einer menschenlesbaren Meldung im obersten PublicReport-Feld zurückgegeben (sowie einem von null verschiedenen StatusCode).

Hinweise

  • Bei allen Parameternamen wird zwischen Groß- und Kleinschreibung unterschieden.
  • Koordinaten verwenden standardmäßig das Format GEODECIMAL_POINT (WGS84 / GPS) mit einem Dezimalpunkt.

Postman

Eine fertige Postman-Collection ist verfügbar: SmartMaps-Address-Search.postman_collection.json. Setzen Sie nach dem Import die Variable basicAuthToken im Tab Variables der Collection auf Ihr Basic-Auth-Token; die Variable baseUrl ist auf die Produktions-Basis-URL voreingestellt.