Address Search API Reference

The SmartMaps Address Search API provides a REST interface for geographic company / address search. It exposes five endpoints: three search endpoints that differ only in how the search location is supplied, one endpoint to fetch records by their supplier/customer ID, and one endpoint to fetch a single record by its internal identifier.

Base URL

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

Authorization

Authentication is done with HTTP Basic Auth. The token is provided per integration by YellowMap and is sent as an Authorization header on every request:

Authorization: Basic <TOKEN>

<TOKEN> is the Base64-encoded combination of the partner name and access key issued by YellowMap — i.e. base64("<SystemPartner>:<SecurityID>"). (apiKey-style query authentication, used by some other SmartMaps APIs, is not accepted here — requests without the Basic header are answered with 401 Unauthorized.)

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

Endpoints

Search by address

GET /addresssearch/ByBranchesAndAddress

Search around separate address fields (postal code, city, street).

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"

Search by position

GET /addresssearch/ByBranchesAndPosition

Radius search starting from a GPS coordinate.

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"

Search by rectangle (bounding box)

GET /addresssearch/ByBranchesAndRectangle

Search inside a rectangle, e.g. the visible map section.

Lux/Luy = upper-left corner, Rlx/Rly = lower-right corner of the rectangle.

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"

Get records by customer / provider ID

GET /addresssearch/ByCustomerId

Fetch address records by their supplier foreign key(s) — the ProviderForeignKey value from the Identifiers of a search result. Useful for re-fetching specific records that you have stored by their provider ID.

Pass one or more ProviderForeignKey IDs; combine several with |.

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

The response uses the same response structure as the search endpoints.

Get a single record by identifier

GET /addresssearch/ByIdentifier

Fetch a single record by its identifier (YMID), e.g. for a detail view.

The value of Identifier is the YMID field from a search response and must be URL-encoded (e.g. YMIDUrlEncoded from the search response can be used directly).

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

The response uses the same response structure as the search endpoints, but always contains exactly one hit (Paging.MaxCount: 1).

Parameter reference

Logging

Authentication itself is done via the HTTP Basic Auth header — see Authorization.

Content

Location

Result control

Identifier

Advanced

Addition parameters

Addition carries its own key=value pairs. The most common use is a reference point for the distance calculation:

With both keys set, every result contains BasicData.Geo.Distance — the straight-line distance to that point in metres. Without them the field stays empty.

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

See Store locator by map area for a complete request.

Response structure

All endpoints (search, ByCustomerId and ByIdentifier) return the same JSON object. The three main parts are GeoItems, Paging and AddressItems; the response also carries several auxiliary containers (usually empty arrays unless relevant for the query/data) and some status fields:

{
  "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 of the search location

Paging — pagination

AddressItems[] — result records

Each element in AddressItems represents one hit (a dealer, branch, store, etc.). The core data is in BasicData; alongside it each item also has Comments, AdditionalContacts, HotelReservationData, ImmoData, History and Similarity (see Further fields per AddressItem below).

BasicData contains: Identifiers, Address, Contact, Geo, BranchListElements, Marketing, BusinessData, AdditionalInfo, MemoItems, Images, ObjectListItems, ReleaseManagement and Copyright. The most relevant ones:

BasicData.Identifiers

BasicData.Address

BasicData.Contact

BasicData.Geo

BasicData.BranchListElements[]

BasicData.Marketing

BasicData.BusinessData

BasicData.AdditionalInfo

BasicData.MemoItems[] and BasicData.Images[]

MemoItems carries structured notes for the record — most notably opening hours (the legacy AddressSearch web service uses pipe-separated values with Mask types NONE, MASK_1 … MASK_5). Images carries images/logos. Both are often empty arrays depending on the dataset.

Further fields per AddressItem

Example response (shortened)

{
  "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
}

Category codes

The Branches parameter expects category codes that are specific to your integration. There is no generic, public list of codes — the codes available for your data (and, where applicable, a base code for the full assortment) are agreed upon when the integration is set up. Additional codes can be enabled on request.

Combining category codes

A single code (Branches=<branchcode>) is enough; several codes are AND-linked with & and must be passed URL-encoded as %26 in the query string. Some integrations also expect a base code for the full assortment to be included — this is part of the integration configuration.

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

Resolved: <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"

Errors

• Missing Authorization header → 401 Unauthorized with body "Access to the system has been denied. Basic authentication header missing."
• Missing required parameters → 400 Bad Request with a plain JSON string message, e.g. "Eine oder mehrere Branchen sind erforderlich." (no Branches) or "Die Angabe des X-Wertes der Standortkoordinate ist nicht korrekt. …" (missing/invalid coordinates).
• Other server-side problems are returned as 200 OK with an empty result set and a human-readable message in the top-level PublicReport field (and a non-zero StatusCode).

Notes

• All parameter names are case-sensitive.
• Coordinates use the default format GEODECIMAL_POINT (WGS84 / GPS) with a decimal point.

Postman

A ready-made Postman collection is available: SmartMaps-Address-Search.postman_collection.json. After importing it, set the basicAuthToken variable in the collection's Variables tab to your Basic Auth token; the baseUrl variable is preset to the production base URL.