Autosuggest

GET

https://api.woosmap.com/what3words/autosuggest

AutoSuggest can take a slightly 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.

Rate limit: 20/1s

Ratelimit: 20/1s

Authorization

key

apiKey query

Public key of the project usually starts with woos-

private_key

apiKey query

Private key with or without write permission.

X-Api-Key

apiKey header

Private key with or without write permission.

Query Parameters

input

string 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.

Example: couch.spotted.a

focus

object

This is a location, specified as latitude,longitude (often where the user making the query is). If specified, the results will be weighted to give preference to those near the focus.

Example: 48.861026,2.335853

clip-to-country

object

Restricts AutoSuggest to only return results inside the countries specified by comma-separated list of ISO 3166-1 alpha-2 country codes.

Example: FR

clip-to-bounding-box

object

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.

Example: 48.624314,1.804429,49.058148,2.908555

clip-to-circle

object

Restrict AutoSuggest results to a circle, specified by lat, lng, kilometres, where kilometres is the radius of the circle.

Example: 48.839701,2.291878,20

clip-to-polygon

object

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 pairs. The API is currently limited to accepting up to 25 pairs.

Example:

48.823547,2.199174,48.823547,2.199174,48.922216,2.328709,48.888626,2.473673,48.819279,2.445513,48.784865,2.330668,48.823547,2.199174

input-type

string Defaults to text

For power users, used to specify voice input mode.

Show 4 enum values Hide 4 enum values

text

vocon-hybrid

nmdp-asr

generic-voice

prefer-land

boolean Defaults to true

Makes AutoSuggest prefer results on land to those in the sea.

language

object

For normal text input, specifies a fallback language, which will help guide AutoSuggest if the input is particularly messy. A supported address language as an ISO 639-1 2 letter code.

Example: fr

Response

200 application/json

Successful Response

suggestions

object[] required

Show 6 propertiesHide 6 properties

suggestions. country

string required

Country Code

suggestions. nearestPlace

string required

Nearest Place

suggestions. words

string required

The what3words address

suggestions. distanceToFocusKm

integer

Distance to the Lat Lng focus (if provided)

suggestions. rank

integer required

Suggestion Rank

suggestions. language

string required

Language Code

Errors

401

Unable to locate credentials.

application/json

detail

string required

402

Out of free quota.

application/json

detail

string required

403

Credentials found, but not matching.

application/json

detail

string required

422

Validation Error

application/json

detail

object[]

Show 3 propertiesHide 3 properties

detail. loc

any[] required

detail. msg

string required

detail. type

string required

429

Rate limit reached

application/json

details

string required

            curl -L -X GET 'https://api.woosmap.com/what3words/autosuggest?input=couch.spotted.am&clip-to-country=fr&key=YOUR_PUBLIC_API_KEY' \
-H 'Referer: http://localhost'

            import requests

url = "https://api.woosmap.com/what3words/autosuggest?input=couch.spotted.am&clip-to-country=fr&key=YOUR_PUBLIC_API_KEY"

payload={}
headers = {
    'Referer': 'http://localhost'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

            var requestOptions = {
  method: 'GET',
  redirect: 'follow'
};

fetch("https://api.woosmap.com/what3words/autosuggest?input=couch.spotted.am&clip-to-country=fr&key=YOUR_PUBLIC_API_KEY", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

            {
  "suggestions": [
    {
      "country": "FR",
      "distanceToFocusKm": 4,
      "language": "en",
      "nearestPlace": "Paris",
      "rank": 1,
      "words": "couches.spotted.alas"
    },
    {
      "country": "FR",
      "distanceToFocusKm": 8,
      "language": "en",
      "nearestPlace": "Paris",
      "rank": 2,
      "words": "couches.spotted.atom"
    },
    {
      "country": "FR",
      "distanceToFocusKm": 30,
      "language": "en",
      "nearestPlace": "Pontcarré, Seine-et-Marne",
      "rank": 3,
      "words": "couch.spotted.boat"
    },
    {
      "country": "FR",
      "distanceToFocusKm": 27,
      "language": "en",
      "nearestPlace": "Triel-sur-Seine, Yvelines",
      "rank": 4,
      "words": "vouch.spotted.dare"
    }
  ]
}

    