Returns suggestions useful when filling out the input fields for a Location by Address request.
This allows to build an interactive address input:
- While the user is typing in one of the input fields for Locations by Address, the frontend can automatically obtain suggestions for this field and display them to the user.
- When the user selects one of the suggestions, the input fields can be updated accordingly.
- Once all information is complete, Locations by Address can be called, to obtain Locations with coordinates.
Input
Suggestions can be requested for the following Locations by Address input fields (see there):
- COUNTRY,
- LOCALITY,
- POSTAL_CODE,
- STREET or
- HOUSE_NUMBER.
Which of these is used is given in the input parameter inputField.
The other parameters contain the data that is already entered in the address input fields:
- country
- state
- locality
- postalCode
- street
- houseNumber.
The endpoint does not have any other parameters, like e.g. language or countryFilter (see below).
Output
If the request succeeds, the response is a list of suggestion records. The list can be empty if nothing suitable is found, e.g when a city name is misspelled or does not exist in the country given.
Suggestion record fields
A suggestion record has a caption field, plus one field for each Locations by Address input field.
- The caption is meant to be displayed to the user when presenting a choice of available suggestions, e.g in a dropdown menu.
- The address fields are meant to replace the previous Locations by Address input fields by what the user chose.
Caption
In simple cases the caption will just contain the chosen text for the input field, for which suggestions were requested.
In other cases, some text in braces might be added to make the choice unambiguous, e.g. the country or US state.
Address fields
Once a suggestion record is chosen, its address fields should be copied into the corresponding input fields for the Locations by Address search.
If an address field does not need to be changed, the suggestion record will contain the input, so it can be copied unconditionally.
Language
All strings are returned in the language that best fits the input. If several languages are possible, shorter names are preferred (e.g. "rom" will, if available, return "Rom" (german) and not "Rome" (english) or "Roma" (italian)).