Search for Localities and Postcode

Web Service to Search for Localities and Postcode.
  1. Introduction
  2. Required parameters
  3. Optional parameters
  4. Localities predictions responses
  5. Predictions
  6. Countries included for Standard Postcode search
  7. Countries included for Advanced Postcode search


The Woosmap Localities service is a web service that returns city names, postcodes and suburbs predictions in response to an HTTP request. The request specifies a textual search string and optional geographic bounds. The service can be used to provide autocomplete functionality for text-based geographic searches.

The Woosmap Localities service 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 the desired postcode or city name. All predictions contains additional data (see below) to use directly the results without needing a “Detail request”.

Woosmap Localities provides city name, postocde and suburb name search Worldwide (see countries included below).

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

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.

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 predictions responses

Localities provides a JSON response containing one root elements:

          "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
              "location": {
                "lat": 45.472416,
                "lng": 9.18711


Each prediction result contains the following fields:

(data: "standard")

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

(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