Search for Localities and Postcodes

Web Service to Search for Localities and Postcodes.
  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

Introduction

The Woosmap Localities service is a web service that returns city names and postcodes 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 postcodes or city names 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 search Worldwide and postcode search for Europe (see countries included).

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=paris&key=woos-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx
https://api.woosmap.com/localities/autocomplete/?input=7501&key=woos-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx

Optional parameters

Localities predictions responses

Localities provides a JSON response containing one root elements:

        {
          "localities": [
            {
              "description": "92100, Hauts-de-Seine, France",
              "name": "92100",
              "admin_0": "France",              
              "admin_1": "Hauts-de-Seine",
              "type": "postal_code",
              "public_id": "TvcsIj+W2iJ+j5/HN/F+5iiamGA="
              "viewpoint": {
                "bounds": {
                  "east": 2.369166,
                  "south": 48.845943,
                  "north": 48.86196,
                  "west": 2.344758
                }
              },
              "location": {
                "lat": 48.88731,
                "lng": 2.3067129
              }
            },
            {...},
            {...},
            {...}
          ]
        }

Predictions

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  

(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), Luxembourg (lu), 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)