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

string

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

string

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

string

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

string

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

string

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

string

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 | null

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"
    }
  ]
}

    