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
Autorisierung
Die Authentifizierung erfolgt über HTTP Basic Auth. Das Token wird pro Integration von YellowMap
bereitgestellt und bei jeder Anfrage als Authorization-Header gesendet:
<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
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
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)
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
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
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.
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_1 …
MASK_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.
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 Unauthorizedmit dem Body"Access to the system has been denied. Basic authentication header missing." - Fehlende erforderliche Parameter →
400 Bad Requestmit einer einfachen JSON-String-Meldung, z. B."Eine oder mehrere Branchen sind erforderlich."(keinBranches) oder"Die Angabe des X-Wertes der Standortkoordinate ist nicht korrekt. …"(fehlende/ungültige Koordinaten). - Andere serverseitige Probleme werden als
200 OKmit einer leeren Ergebnismenge und einer menschenlesbaren Meldung im oberstenPublicReport-Feld zurückgegeben (sowie einem von null verschiedenenStatusCode).
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.