Autocomplete
Get address suggestions while typing
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”):
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.
{
"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",
},
],
"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.
{"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:
- Maximum of 50 queries per second (QPS) per Project (so possibly the sum of client-side and server-side queries)
