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
    5. extended
  4. Localities suggestions responses
  5. Suggestions
    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 suggestions.

The returned suggestions are designed to be presented to the user to aid them in selecting their desired location. All suggestions 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 suggestions, 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 suggestion 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.

extended

If set, this parameter allows a refined search over locality names that bears the same postal code. By triggering this parameter, integrators will benefit from a search spectrum on the locality type that includes postal codes. To avoid confusion, it is recommended not to activate this parameter along with the postal_code type which could lead to duplicate locations. Also, the default description returned by the API changes to name (postal code), admin_1, admin_0. It is only available for France and Italy.

Localities suggestions 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 Suggestion 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
      }
    },
    {...},
    {...},
    {...}
  ]
}

Suggestions

Each suggestion 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 suggestion.

viewpoint

contains geographic bounds to help center a map on a suggestion’s selection by the user.

description

is the concatenation of name, admin_1, admin_0 to be used as suggestion 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 for France or it for Italy 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