Autocompletion

Basic principles

This automatic completion service, or autocomplete, saves internauts time when entering location or address. The function suggests likely locations as the letters of an address are typed in, or even as they are deleted, in the localisation input field.

example: the internaut enters "avenue des cha», and the service returns «Avenue des Champs-Élysées, Paris», as well as other addresses starting with the same string.

The location names are ranked or graded according to a weighting that allows the most probable solutions to be presented first, taking into account the size of the town.

[Warning] Warning

This web service is not part of the geocoding operation. The geocoding web service can be used with the data received from the autocomplete service, taking the address found by the autocomplete module as an entry parameter of the geocoder.

To ensure optimised performances, we advise building the geocoding from the result of the autocomplete operation with separate fields, and not basing the geocoding on fulltext fields (both of these are provided in the autocomplete result).

See too Autosuggest web service.

Autocompletion example 

{
        "url":"https://api.geoconcept.com/EU/GCW/geoconcept-web/api/lbs/autocomplete/v3.json",
        "type":"GET",
        "params": {
                "text": {
                        "sample":"Avenue des cha"
                },
                "maximumResponses": {
                        "sample":"3"
                },
                "countryCode": {
                        "sample":"FR"
                },
                "matchLevels": {
                        "sample":"fromLabel"
                }
        }
}

Parameters / properties

Input

parameter description optional default

text

Location address to enter

yes

maximumResponses

maximum number of results for addresses in the response.
if the value is left empty, the parameter defined by default will apply

yes

10

bounds

Sets a focus on a geographic area represented by the top-left and the bottom-right corners (so longitude-min,latitude-min;longitude-max,latitude-max) of a bounding box so the results within this area are more important than results outside of this area. ex: &bounds=2.3222,48.8111;2.4222,48.9111
Can be combined with the countryCode.

yes

center

Sets a focus on a geographic point represented by a single geo-coordinate pair, comma separated, so the results nearby this point are more important than results far from this point. ex: &center=2.3222,48.8111
Can be combined with the countryCode.

yes

countryCode

The countryCode parameter limits suggestions to a country (2-letter ISO country codes)
Can be combined with the bound or center parameters.

yes

language

The preferred language of address elements in the result. The language parameter must be provided as 2-letter ISO language code.

yes

matchLevels

Filter match precision, one of: houseNumber, intersection, street, postalCode, district, city, county, state, country or fromLabel. To use geocoding web service with the data received from the autocomplete service it is recommended to use the parameter matchLevels=fromLabel.

yes

Output

property type min/max description

fulltext

string

0/1

Location found with a specific nomenclature including the post code and the name of the town.

language

string

0/1

Location result language (2-letter ISO language code).

countryCode

string

0/1

Country code of the location (2-letter ISO country code).

matchLevel

string

0/1

Match precision. One of: houseNumber, intersection, street, postalCode, district, city, county, state, country.

distance

string

0/1

Distance in meters from the search center. Only available for queries with bound or center parameter.

country

string

0/1

Country of the address found

state

string

0/1

State of the address found

county

string

0/1

County of the address found

city

string

0/1

City of the address found

postCode

string

0/1

Postal code of the address found

district

string

0/1

District of the address found

street

string

0/1

Street of the address found

streetNumber

string

0/1

Street number of the address found

Possible returns

The case of addresses that are found (status est OK)  

{
   "message":null,
   "status":"OK",
   "results":[
      {
         "fulltext":"Avenue des Champs-Élysées, 75008 Paris",
         "language":"fr",
         "countryCode":"FR",
         "matchLevel":"street",
         "distance":0.0,
         "country":"France",
         "state":"Île-de-France",
         "county":"Paris",
         "city":"Paris",
         "postCode":"75008",
         "district":"8e Arrondissement",
         "street":"Avenue des Champs-Élysées",
         "streetNumber":null
      },
      {
         "fulltext":"Avenue des Champs Lasniers, 91940 Les Ulis",
         "language":"fr",
         "countryCode":"FR",
         "matchLevel":"street",
         "distance":0.0,
         "country":"France",
         "state":"Île-de-France",
         "county":"Essonne",
         "city":"Les Ulis",
         "postCode":"91940",
         "district":null,
         "street":"Avenue des Champs Lasniers",
         "streetNumber":null
      },
      {
         "fulltext":"Avenue des Charmes, 94520 Périgny",
         "language":"fr",
         "countryCode":"FR",
         "matchLevel":"street",
         "distance":0.0,
         "country":"France",
         "state":"Île-de-France",
         "county":"Val-de-Marne",
         "city":"Périgny",
         "postCode":"94520",
         "district":null,
         "street":"Avenue des Charmes",
         "streetNumber":null
      }
   ]
}

The case of an address that does not exist (status is OK)  

{
   "message":null,
   "status":"OK",
   "results":[
   ]
}

Prev  Up  Next
  Home