Autocomplete

Get address suggestions while typing

  1. Introduction
  2. Required Parameters
  3. Optional Parameters
  4. Responses
  5. 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.

Former method to call geocode endpoint to retrieve details for a suggestion remains available but is now deprecated.

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

To restrict your results to specific areas. Currently, you can use components to filter over countries. Countries must be passed as three characters string (ISO 3166-1 Alpha 3).
Components should be passed as an array of different options which are separated by a |
components=country:FRA
or
components=country:CAN|country:BEL

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.

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": "aGVyZTpjbTpuYW1lZHBsYWNlOjIwDDA1MTI2YWRkZWQ=",
      "description": "Rue de l'Ouest, 44100 Nantes, France",
      "matched_substring": {
        "description": [
          {
            "offset": 0,
            "length": 14
          }
        ]
      },
      "type": "route"
    },
    {
      "public_id": "aGVyZTpjberrusYWNlOjIwDDA1MTI2YWRkZWQ=",
      "description": "Rue de l'Ouest, 75014 Paris, France",
      "matched_substring": {
        "description": [
          {
            "offset": 1,
            "length": 12
          }
        ]
      },
      "type": "route"
    }
  ],
  "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:

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