Autocomplete

Get address suggestions while typing

  1. Introduction
  2. Required Parameters
  3. Optional Parameters
  4. Address Autocomplete example
  5. Responses
  6. Usage limits

Introduction

Woosmap Address Autocomplete endpoint provides autocompletion suggestions for a given input.

A Woosmap Address Autocomplete request is an HTTP URL of the following form:

        https://api.woosmap.com/address/autocomplete/json?parameters

    

To get geometry info (lat/lng, viewport) and/or address components (street number, locality, …) on a suggestion you should request the details endpoint with the public_id field value as request parameter.

Required Parameters

Certain parameters are required to initiate an Autocomplete request. As is standard in URLs, all parameters are separated using the ampersand(&) character. Few parameters are mandatory. Either a field of input must be present in addition to a Woosmap API key.

        https://api.woosmap.com/address/autocomplete/json?input=new%20yo&key={PUBLIC_API_KEY}

    

input

The input string of which to autocomplete. The input must be URL encoded for example space is %20.

key

Your project’s API key. This key identifies your Woosmap Project for purposes of security and quota management. Public keys are designed to be used client side, where every request contain a referer.

Reminder: To use the Address API, your Public API key (parameter key) has to be authorized for the domains and/or IPs (referer) where you make the call. More on securing API keys here.

private_key

Your project’s private API key. This key identifies your Woosmap Project for purposes of security and quota management. Private keys are designed to be used server side, no referer checking associated with those keys.

Optional Parameters

language

The language to return the address elements in. Must be a ISO 639-1 language code.

location

Bias for the results. Should be pass in lat,lng format (example : 5.2,-2.3)

components

Geographic places to which you would like to restrict your results. Currently, you can use components to filter over countries. Countries are identified by a two character, ISO 3166-1 Alpha-2 or a three character, ISO 3166-1 Alpha-3 compatible country code. Multiple countries must be passed as separates components, with the pipe character (|) as a separator.

If the request contains multiple countries (eg. components=country:FRA|country:ITA), the API looks for addresses where country=FRA OR country=ITA. If no address match one of those two values, a ZERO_RESULTS message is returned.

Example

components=country:fr or components=country:fra would restrict your results to places within France.

Multiple countries example

components=country:gb|country:fr|country:be|country:sp|country:it would restrict your results to the United Kingdom, France, Belgium, Spain and Italy.

Address Autocomplete example

A request for address containing the string “Lond” within the Great Britain (country “GB”):

Address Autocomplete call
        https://api.woosmap.com/address/autocomplete/json
  ?components=country%3Agb
  &input=Lond
  &key=YOUR_PUBLIC_API_KEY
    
        curl -L -X GET 'https://api.woosmap.com/address/autocomplete/json?input=Lond&components=country%3Agb&key=YOUR_PUBLIC_API_KEY' \
-H 'Referer: http://localhost'

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

fetch("https://api.woosmap.com/address/autocomplete/json?input=Lond&components=country%3Agb&key=YOUR_PUBLIC_API_KEY", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

    
        var axios = require('axios');

var config = {
  method: 'get',
  url: 'https://api.woosmap.com/address/autocomplete/json?input=Lond&components=country%3Agb&key=YOUR_PUBLIC_API_KEY',
  headers: { 
    'Referer': 'http://localhost'
  }
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});


    
        import requests

url = "https://api.woosmap.com/address/autocomplete/json?input=Lond&components=country%3Agb&key=YOUR_PUBLIC_API_KEY"

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

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

print(response.text)


    
        OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("text/plain");
RequestBody body = RequestBody.create(mediaType, "");
Request request = new Request.Builder()
  .url("https://api.woosmap.com/address/autocomplete/json?input=Lond&components=country%3Agb&key=YOUR_PUBLIC_API_KEY")
  .method("GET", body)
  .addHeader("Referer", "http://localhost")
  .build();
Response response = client.newCall(request).execute();

    
        require "uri"
require "net/http"

url = URI("https://api.woosmap.com/address/autocomplete/json?input=Lond&components=country%3Agb&key=YOUR_PUBLIC_API_KEY")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Referer"] = "http://localhost"

response = https.request(request)
puts response.read_body


    

Responses

Autocomplete provides a JSON response containing one root element, predictions which contains an array of proposals. A more accurate request should return one proposal, whereas a less accurate request may return multiple.

Address Autocomplete Collection Response
JSON
        {
  "predictions":
    [
      {
        "public_id": "aGVyZTpjbTpuYW1lZHBsYWNlOjIwMzM3NDU0",
        "description": "London, England, United Kingdom",
        "matched_substring": { "description": [{ "offset": 0, "length": 4 }] },
        "type": "locality",
      },
      {
        "public_id": "aGVyZTpjbTpuYW1lZHBsYWNlOjIwNDE5Nzgz",
        "description": "Londonderry, Northern Ireland, United Kingdom",
        "matched_substring": { "description": [{ "offset": 0, "length": 4 }] },
        "type": "locality",
      },
      {
        "public_id": "aGVyZTpjbTpuYW1lZHBsYWNlOjIwNDExMTIz",
        "description": "County Londonderry, Northern Ireland, United Kingdom",
        "matched_substring": { "description": [{ "offset": 7, "length": 4 }] },
        "type": "admin_level",
      },
    ],
  "status": "OK",
}

    

Predictions

Each result contains the following fields:

description

Contains the text description of the proposal to be used as suggestion in drop down list if needed.

matched_substring

contains a set of substrings of description field, that match elements in the input. It can be used to highlight those substrings. Each substring is identified by an offset and a length.

JSON
        {"description":[{"offset": 0, "length": 6 }]}

    

type

Contains the type of result. Can be any value from following list:
house_number route address_block locality admin_level country

public_id

The public_id of the suggestion. Unique by suggestion, it can be used to retrieve details (geometry or/and address_components attributes) associated to a suggestion.

status

Returns more info on if the request was successful or not, valid responses:

OK indicates the response contains a valid result.
INVALID_REQUEST indicates that the provided request was invalid (e.g. wrong URL syntax).
REQUEST_DENIED indicates that the service denied use of the Address API (e.g. wrong API Key, wrong/no referer, …).
UNKNOWN_ERROR indicates an Address API request could not be processed due to a server error. The request may succeed if you try again.

Usage limits

The following usage limits are in place for the Address API on the autocomplete endpoint:

Was this article helpful?
Have more questions? Submit a request