This method is in a preview state, the API is stable, feature changes could be introduced in future.
Returns suggestions useful when filling out the input field for a Locations by Text request.
This allows to build an interactive address input:
- While the user is typing in the input field for Locations by Text, the frontend can automatically obtain suggestions and display them to the user.
- When the user selects one of the suggestions, the input field can be updated accordingly.
- At any time Locations by Text can be called, to obtain Locations with coordinates.
Input
Suggestions can be requested for any search text that could also be used for a Locations by Text request.
Country filters reduce the search space and can improve performance. Country codes should be ISO 3166-1 alpha-2 and separated by a comma. In countries such as US, RU, AU, CA, and IN results can also be filtered by country subdivision specified as ISO 3166-2. In case the requested subdivision is not available, the results are filtered by the country and a warning is attached to the response.
A search center can be defined with the center parameter, sorting all suggestions according to their proximity to the center. The closer a suggested location is to the center, the higher it will be in the list of suggestions.
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.
Suggestion record fields
A suggestion record has a caption and a sub caption field. Both fields are meant to be displayed to the user when presenting a choice of available suggestions, e.g in a dropdown menu.
Caption
The caption contains the suggested search text for a Locations by Text request which normally is the exact name of a location (e.g. name of a city or a street).
Sub caption
The sub caption gives additional information for the location given in the caption. This can be for example the name of an admin region, country or US state.
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)).