Autocomplete web service for geographical places

Add a powerful autocomplete service to your projects
  1. Introduction
  2. Required Parameters
    1. input
    2. key
  3. Optional parameters
    1. types types=postal_code
    2. components
    3. language
    4. data
  4. Localities predictions responses
  5. Predictions
    1. name
    2. location
    3. public_id
    4. type
    5. admin_0
    6. admin_1
    7. viewpoint
    8. description
    9. postal_codes
    10. postal_town
    11. matched_substrings
  6. Localities in native mobile apps
  7. Countries included for Standard Postcode search (data=standard)
  8. Countries included for Advanced Postcode search (data=advanced)

Introduction

Woosmap Localities API is a web service that returns a great amount of geographical places in response to an HTTP request. Among others are city names, postcodes, suburbs or even airports! You can find the full list of supported types below.

The request specifies a textual search string and optional geographic bounds. It can be used to provide autocomplete functionality for text-based geographic searches.

The Localities API can match on full words as well as substrings. You can therefore send queries as the user types, to provide on-the-fly city names, postcodes or suburb name predictions.

The returned predictions are designed to be presented to the user to aid them in selecting their desired location. All predictions contain additional data (see below) to use directly the results without needing another request. It is possible to make direct API calls through the Localities REST API, or use either our JavaScript Library or Widget to add a powerful autocomplete feature to your projects.

The Localities API provides worldwide predictions, unless specified otherwise in the available types (see countries included below).

A Woosmap Localities autocomplete request is an HTTP URL of the following form:

https://api.woosmap.com/localities/autocomplete/?parameters

Required Parameters

Certain parameters are required to initiate a Localities request. As is standard in URLs, all parameters are separated using the ampersand (&) character. The list of parameters and their possible values are enumerated below.

https://api.woosmap.com/localities/autocomplete/?input=london&key=woos-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx

input

The text string on which to search. Localities API will return candidate matches based on this string and order results based on their perceived relevance.

key

Your project’s API key. This key identifies your Woosmap Project for purposes of quota management.

Reminder: To use the Localities 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.

Optional parameters

.../localities/autocomplete/?input=lond&key=woos-xxxx&types=postal_code&components=country:gb&language=en&data=advanced

types types=postal_code

The types of predictions to return. Several types are available, see the list below:

locality includes locality names and suburbs worldwide
postal_code publicly-used postcodes around the world
admin_level most commonly used administrative areas
country countries as whole point of interest
airport includes all medium sized to international sized airports
train_station includes all train stations
metro_station includes all metro stations
shopping includes shopping malls (or “shopping centers”) - may include private retail brands
museum includes museums
tourist_attraction includes tourist attractions like the Eiffel tower
amusement_park includes amusement parks like Disneyland Paris
art_gallery includes art galleries
zoo includes zoos

Not specifying any type will only query locality and postal_code. Multiple types can be passed using the pipe character (|) as a separator. For example: types=locality|airport|admin_level.

components

A grouping of places to which you would like to restrict your results. Currently, you can use components to filter over countries. Countries must be passed as a two character, ISO 3166-1 Alpha-2 compatible country code. For example: components=country:fr would restrict your results to places within France and components=country:fr-fr returns locations only in Metropolitan France. Multiple countries must be passed as multiple country:XX filters, with the pipe character (|) as a separator. For example: components=country:gb|country:fr|country:be|country:sp|country:it would restrict your results to city names or postcodes within the United Kingdom, France, Belgium, Spain and Italy.

language

The language code, indicating in which language the results should be returned, if possible. Searches are also biased to the selected language; results in the selected language may be given a higher ranking. If language is not supplied, the Localities service will use the default language of each country. No language necessary for postal_code request.

data

Two values for this parameter: standard or advanced. By default, if the parameter is not defined, value is set as standard. The advanced value opens suggestions to worldwide postcodes in addition to postcodes for Western Europe. A dedicated option subject to specific billing on your license is needed to use this parameter. Please contact us if you are interested in using this parameter and you do not have subscribed the proper option yet.

Localities predictions responses

Localities provides a JSON response containing one root element, localities which contains an array of places, with information about the postcode or the city. See Localities Predictions Results for information about these results. The Localities API returns up to 5 results.

{
  "localities": [
    {
      "description": "20121, Milano, Italy",
      "name": "20121",
      "admin_0": "Italy",              
      "admin_1": "Milano",
      "postal_town": "Milano",
      "type": "postal_code",
      "public_id": "MkvnYy6K6oVGqeqfWJGO/6eCgqo=",
      "viewpoint": {
        "bounds": {
          "east": 9.205397,
          "south": 45.463764,
          "north": 45.482056,
          "west": 9.169627
        }
      },
      "matched_substrings": {
        "name": [{"offset": 0, "length": 5}],
        "admin_1": [{"offset": 0, "length": 3}],
        "description": [{"offset": 0, "length": 5}, {"offset": 7, "length": 3}],
        "postal_town": [{"offset": 0, "length": 3}]
      },
      "location": {
        "lat": 45.472416,
        "lng": 9.18711
      }
    },
    {...},
    {...},
    {...}
  ]
}

Predictions

Each prediction result contains the following fields:

name

contains the human-readable name for the returned result. For postal_code results, this is directly the postcode value. For locality results, name in the specified language is returns. If no language is specified, default name (country local language) is returned.

location

contains latitude and longitude of the searched city or postcode. For postal_code results, coordinates represent the center of the area. For locality results, coordinates represent the center of the populated area.

public_id

contains a unique ID for each suggestion. Please use this ID if you need to give us feedbacks on results.

type

contains the type of the suggestion, either locality, postal_code, admin_level, airport, train_station, metro_station, shopping, museum, zoo, amusement_park, art_gallery, tourist_attraction or country.

admin_0

contains the country name.

admin_1

contains the administrative level including the prediction.

viewpoint

contains geographic bounds to help center a map on prediction selection by a user.

description

is the concatenation of name, admin_1, admin_0 to be used as prediction in drop down list if needed.

postal_codes

contains an array of known postal codes for a locality (only available on suggestions with country:fr and type: locality).

postal_town

contains the larger city (or the post office city) for a postal_code (only available on suggestions with type: postal_code).

matched_substrings

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

Localities in native mobile apps

It is possible to enjoy the power of Localities API directly within a native mobile app by making REST API calls using your projects’ private_key.

https://api.woosmap.com/localities/autocomplete/?input=london&private_key=[YOUR_PRIVATE_KEY]

Countries included for Standard Postcode search (data=standard)

Austria Austria Belgium Belgium Canada Canada
Denmark Denmark Finland Finland France France
Germany Germany Iceland Iceland Ireland Ireland
Italy Italy Luxembourg Luxembourg Malta Malta
Netherlands Netherlands Norway Norway Portugal Portugal
Spain Spain Sweden Sweden Switzerland Switzerland
United Kingdom United Kingdom United States United States  

Countries included for Advanced Postcode search (data=advanced)

A dedicated option subject to specific billing on your license is needed to use this parameter. Please contact us if you are interested in using this parameter and you do not have subscribed the proper option yet.

Afghanistan (af), Albania (al), Algeria (dz), Argentina (ar), Armenia (am), Australia (au), Azerbaijan (az), Bahrain (bh), Bangladesh (bd), Belarus (by), Bermuda (bm), Bhutan (bt), Bosnia-Herzegovina (ba), Brazil (br), Brunei Darussalam (bn), Bulgaria (bg), Cambodia (kh), Canada (ca), Cape Verde (cv), Anguilla (ai), British Virgin Islands (vg), Cayman Islands (ky), Cuba (cu), Dominican Republic (do), Haiti (ht), Jamaica (jm), Montserrat (ms), Puerto Rico (pr), Saint Martin (mf), Turks and Caicos (tc), US Virgin Islands (vi), Chile (cl), China (cn), Colombia (co), Costa Rica (cr), Croatia (hr), Cyprus (cy), Czech Republic (cz), _Faroe Islands (fo), _Greenland (gl), Ecuador (ec), Egypt (eg), El Salvador (sv), Estonia (ee), Falkland Islands (fk), Georgia (ge), Greece (gr), Guatemala (gt), Honduras (hn), Hungary (hu), India (in), Indonesia (id), Iran (ir), Iraq (iq), Israel (il), Japan (jp), Jordan (jo), Kazakhstan (kz), Kenya (ke), Kosovo (xk), Kuwait (kw), Kyrgyzstan (kg), Laos (la), Latvia (lv), Lebanon (lb), Liberia (lr), Lithuania (lt), Macedonia (mk), Madagascar (mg), Malaysia (my), Maldives (mv), Malta (mt), Mauritius (mu), Mexico (mx), Moldova (md), Mongolia (mn), Montenegro (me), Morocco (ma), Mozambique (mz), Myanmar (mm), Nepal (np), New Zealand (nz), Nicaragua (ni), Nigeria (ng), Oman (om), Pakistan (pk), Palestine (ps), Panama (pa), Papua New Guinea (pg), Paraguay (py), Peru (pe), Philippines (ph), Poland (pl), Romania (ro), Russia (ru), Saudi Arabia (sa), Senegal (sn), Serbia (rs), Singapore (sg), Slovakia (sk), Slovenia (si), South Africa (za), South Georgia (gs), South Korea (kr), Sri Lanka (lk), Swaziland (sz), Taiwan (tw), Tajikistan (tj), Tanzania (tz), Thailand (th), Tunisia (tn), Turkey (tr), Turkmenistan (tm), USA (us), Ukraine (ua), Uruguay (uy), Uzbekistan (uz), Venezuela (ve), Viet Nam (vn), Western Sahara (eh)

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