Autosuggest
AutoSuggest can take an incorrect 3 word address and suggest a list of valid 3 word addresses. It has powerful features that can, for example, optionally limit results to a country or area, and prioritise results that are near the user (see Clipping and focus, below).
Autosuggest provides corrections for the following types of input error:
- Typing errors
- Spelling errors
- Mistaken words (e.g. singular vs. plural)
- Words in the wrong order
AutoSuggest accepts either a full or partial 3 word address (it will be partial if the user is still typing in a search box, for example). A partial 3 word address must contain at least the first two words and first character of the third word. For example filled.count.s
will return results, but anything shorter will not.
Clipping and focus
Clipping allows you to specify a country (or list of countries) and/or geographic area to exclude results that are not likely to be relevant to your users. To give a more targeted, shorter set of results to your users, we recommend you use the clipping parameters. If you know your user’s current location, we recommend that you use the focus
to return results that are likely to be more relevant (i.e. results near the user).
In summary, the clipping policy is used to optionally restrict the list of candidate AutoSuggest results, after which, if focus
has been supplied, this will be used to weight the results in order of relevance to the focus
.
Multiple clipping policies can be specified, though only one of each type. For example you can clip to country and clip to circle in the same AutoSuggest call, and it will clip to the intersection of the two (results must be in the circle AND in the country). However, you can't specify two clip-to-circle
policies in the same call.
Language
AutoSuggest will search in all languages. However, you can additionally specify a fallback language, to help the API in situations where the input is unclear. For normal text input, the language
parameter is optional, and AutoSuggest will work even without a language
parameter. However, for voice input the language
should always be specified.
Results
As well as Nuance-based speech recognition systems, AutoSuggest
also supports a Generic Voice option. This supports output from any speech recognition software. This input type handles spaces between words, for example, 'filled count soap'. Users should not pronounce 'dot' when speaking a 3 word address, and this input type not handle text in languages in which words are not separated by spaces, e.g. Chinese. Language detection should be disabled, so language
must always be set.
Resource URL
https://what3words.search.hereapi.com/v3/autosuggest
Parameters
Parameter | Required/optional | Description | Example |
key | required | A valid API key; if not supplied as a parameter, a key must be supplied as a request header | key=[API-KEY] |
input | required | The full or partial 3 word address to obtain suggestions for. At minimum this must be the first two complete words plus at least one character from the third word. | input=plan.clips.a |
focus | optional | This is a location, specified as latitude,longitude (often where the user making the query is). If specified, the results will be weighted togive preference to those near the focus . For convenience, longitude is allowed to wrap around the 180 line, so 361 is equivalent to 1. | focus=51.521251,-0.203586 |
clip-to-country | optional | Restricts AutoSuggest to only return results inside the countries specified by comma-separated list of uppercase ISO 3166-1 alpha-2country codes (for example, to restrict to Belgium and the UK, use clip-to-country=GB,BE ).Clip-to-country will also accept lowercase country codes. Entries must be two a-z letters. WARNING: If the two-letter code does not correspond to a country, there is no error: API simply returns no results. | clip-to-country=NZ , |
clip-to-bounding-box | optional | Restrict AutoSuggest results to a bounding box, specified by coordinates.south_lat,west_lng,north_lat,east_lng , where:south_lat less than or equal to north_lat west_lng less than or equal to east_lng . In other words, latitudes and longitudes should be specified order of increasing size. Lng is allowed to wrap, so that you can specify bounding boxes which cross the ante-meridian: -4,178.2,22,195.4 | clip-to-bounding-box=51.521,-0.343,52.6,2.3324 |
clip-to-circle | optional | Restrict AutoSuggest results to a circle, specified by lat,lng,kilometres , where kilometres in the radius of the circle. For convenience, longitude is allowed to wrap around 180 degrees. For example 181 is equivalent to -179. | clip-to-circle=51.5 |
clip-to-polygon | optional | Restrict AutoSuggest results to a polygon, specified by a comma-separated list of lat,lng pairs. The polygon should be closed, i.e. the first element should be repeated as the last element; also the list should contain at least 4 entries. The API is currently limited to accepting up to 25 pairs. | clip-to-polygon=51.521,-0.343,52.6,2.3324,54 |
input-type | optional | For power users, used to specify voice input mode. Can be text (default),vocon-hybrid , nmdp-asr or generic-voice . | input-type=text |
language | optional | For normal text input, specifies a fallback language, which will help guide AutoSuggest if the input is particularly messy. If specified, thisparameter must be a supported 3 word address language as an ISO 639-12 letter code. For voice input, language must always be specified. | language=fr |
prefer-land | optional | Makes AutoSuggest prefer results on land to those in the sea. This setting is on by default. Use false to disable this setting and receive more suggestions in the sea. | prefer-land=false | `` |
Example requests
Autosuggest
This example returns AutoSuggest results for the partial 3 word address film.crunchy.spiri
; the results are not clipped and not ranked for proximity to a given location.
GET https://what3words.search.hereapi.com/v3/autosuggest?input=film.crunchy.spiri&key=[YOUR-API-KEY]
Autosuggest with focus only
This example returns AutoSuggest results for the partial 3 word address film.crunchy.spiri
; the results are ranked for proximity relevance to the focus
point of 50.842404,4.361177.
GET https://what3words.search.hereapi.com/v3/autosuggest?input=film.crunchy.spiri&focus=50.842404,4.361177&key=[YOUR-API-KEY]
Autosuggest with clip-to-circle
This example searches for plan.clips.a
; the results are constrained to those that are within 10 km of the point 51.4243877,-0.3474524.
GET https://what3words.search.hereapi.com/v3/autosuggest?input=plan.clips.a&clip-to-circle=51.4243877,-0.3474524,10&key=[YOUR-API-KEY]
AutoSuggest with focus and clip-to-country
GET https://what3words.search.hereapi.com/v3/autosuggest?input=plan.clips.a&focus=51.4243877,-0.3474524&clip-to-country=GB&key=[YOUR-API-KEY]
AutoSuggest with clip-to-bounding-box
This searches for plans.clip.a
in the bounding box described by a NE corner of 54,2 and a SW corner of 50,-4.
GET https://what3words.search.hereapi.com/v3/autosuggest?input=plan.clips.a&clip-to-bounding-box=50,-4,54,2&key=[YOUR-API-KEY]
JSON
{
"suggestions": [
{
"country": "BE",
"nearestPlace": "Brussels, Brussels Capital",
"words": "film.crunchy.spirits",
"distanceToFocusKm": 1,
"rank": 1,
"language": "en"
},
{
"country": "ES",
"nearestPlace": "Caldes de Montbui, Catalonia",
"words": "film.crunchy.spirit",
"distanceToFocusKm": 1039,
"rank": 2,
"language": "en"
},
{
"country": "NL",
"nearestPlace": "Weert, Limburg",
"words": "firm.crunchy.spires",
"distanceToFocusKm": 105,
"rank": 3,
"language": "en"
}
]
}