Structured search

GET /address_whisper/structured

Use this when your form has separate fields (city, street, zip, house number…) instead of a single search box. You tell the API which field the user is currently typing into via searchType; that field is completed, and any other fields you pass narrow the candidates.

Query parameters

searchType values

Request

cURL

Code(bash)
 
# Autocomplete the street, filtered to the city the user already picked.
curl -G 'https://api.polaris.launify.com/address_whisper/structured' \
  -H 'Referer: https://yourapp.com' \
  --data-urlencode 'searchType=street' \
  --data-urlencode 'street=Nár' \
  --data-urlencode 'city=Praha' \
  --data-urlencode 'country=CZ' \
  --data-urlencode 'apiKey=YOUR_API_KEY'

JavaScript

Code(js)
 
const url = new URL(
  'https://api.polaris.launify.com/address_whisper/structured',
);
url.searchParams.set('searchType', 'street');
url.searchParams.set('street', 'Nár');
url.searchParams.set('city', 'Praha');
url.searchParams.set('country', 'CZ');
url.searchParams.set('apiKey', 'YOUR_API_KEY');

const suggestions = await fetch(url).then((r) => r.json());

Response

200 OK — an array of up to 13 result objects, collapsed on the active field (e.g. one entry per distinct city when searchType=city). The object shape is identical to Address search, including the structured details.

Code(json)
 
[
  {
    "label": "Národní 223/2, Praha - Nové Město, 11000",
    "value": "Národní 223/2, Praha - Nové Město, 11000",
    "lon": 14.41346,
    "lat": 50.08125,
    "street": "Národní 223/2",
    "city": "Praha - Nové Město",
    "postcode": "11000",
    "country": "CZ",
    "details": {
      "housenumber": "223",
      "orientationnumber": "2",
      "street": "Národní",
      "city": "Praha",
      "district": "Nové Město",
      "postcode": "11000",
      "municipality": "",
      "province": "Středočeský kraj",
      "county": "Hlavní město Praha",
      "state": "",
      "country": "CZ"
    }
  }
]