Skip to content

Address Search

The SmartMaps Address Search API is a REST interface for retrieving address and company records by location. It powers location finders, dealer and branch searches and similar use cases: given a location — an address, a coordinate plus radius or a rectangular map section — and an optional set of category filters, the API returns the matching address records together with contact data, geo coordinates, distances and categories.

Key Features

Three ways to search by location

  • By address — search around separate address fields (postal code, city, street).
  • By position — radius search around a GPS coordinate.
  • By rectangle — search inside a bounding box, e.g. the visible map section.

In addition, records can be fetched directly by ID — several by their supplier/customer ID (ByCustomerId, using the ProviderForeignKey from a result) or a single record by its internal identifier (ByIdentifier), for example to render a detail view.

Category and full-text filters

Every search requires at least one category code (Branches); results can be narrowed further with free-text search terms (Catchwords). The category codes are specific to your integration and are agreed upon when it is set up — see Category codes in the reference.

Consistent JSON response

All endpoints return the same JSON object — the main parts are GeoItems (the geocoded search location), Paging (pagination) and AddressItems (the result records), alongside a few auxiliary containers — so the same parsing code works for every variant. See the API reference for the full schema.

Getting started

Base URL

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

Authorization

Requests are authenticated with HTTP Basic Auth. The token is provided per integration and is sent as an Authorization header on every request:

Authorization: Basic <TOKEN>

Note

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

Quick start

# 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"

For the full list of endpoints, parameters and the response schema, see the API reference.