Autocompletion

Basic principles

This automatic completion service, or autocomplete, saves internauts time when entering a 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 cham», and the service returns «Avenue des Champs-Élysées, Paris», as well as other addresses starting with the same string.

This service takes as input a character string, as an option, an identifier for a territory, and an identifier of the type of entity being sought. From an optimised index, it is capable of instantly providing an extract of all the location names (addresses) starting with this string, in this territory, and of this type.

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

You will need to copy the reference files and configure the service thanks to the Administration interface of Geoconcept Web, see chapter Installing Geoconcept Web / Settings/ UGC parameter settings / Autocomplete web service.

	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).

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).

	Tip
	We recommend a 64-bit UGC Server architecture since autocompletion requires significant resources.

For performance reasons, (since the service has to be called each time the internaut types a character at the keyboard) it will be published in the form of a JSON service. As an option, it can also be called in the form of a JSONP service.

Availability

This web service is available at all times with Geoconcept Web with the reference files.

Version change

Earlier versions of the web service are conserved in Geoconcept Web to ensure compatibility with previous developments. It is recommended that you use the most recent version.

Changes in relation to v2

"zipcode" parameter is renamed "postCode"

V2

Parameters / properties

Input

parameter	description	optional	default
text	Location address to enter	yes
type	Allows selection of the source of the autocomplete files indicating the alias for the latter: if a single autocomplete source exists, the value should remain empty if several sources exist for the autocomplete function, you will need to use the aliases of the latter, defined beforehand cf. Geoconcept Web / Administration / Parameters `geocoder.autocomplete.alias.<alias_name>.datasource` the value of this key must indicate the name of the directory containing the series of files needed for autocompletion.	yes
terr	Filter on the territory where one wants to search for the localising elements in question. example, if you want the query to apply to a town, it will be necessary to enter a postcode : 92220 if you want the search to be applied to several towns or departments, you need to separate the territories with a “;” : 75;78;92 if the value remains empty, the search will be applied to all of the territory covered by the autocomplete files and the results will be sorted in increasing streets alphabetical order.	yes
maximumResponses	maximum number of results for addresses in the response. if the value is left empty, the parameter defined in the Administration will apply	yes	cf. Geoconcept Web / Administration / Parameters `geocoder.autocomplete.maxCandidates`

As output

property	type	min/max	description
city	string	0/1	town found
classification	integer	1/1	code indicating in which category the town returned is found by the webservice. example, the categorisation of HERE tables ranges from 1 (the biggest towns) to 8 (village or hamlet)
country	string	0/1	country on two letters (ISO code 3166-1 or ccTLD) for example "fr" when the result is found in France
fulltext	string	0/1	street found with a specific nomenclature including the post code and the name of the town
street	string	1/1	street found
postCode	string	0/1	post code found

SOAP

WSDL

http://<server>/<webapp>/api/ws/autoCompleteService?wsdl

Query

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sch="http://geoconcept.com/gc/schemas">
   <soapenv:Header/>
   <soapenv:Body>
      <sch:autocompleteV2>
         <!--Optional:-->
         <text>rue noire</text>
         <!--Optional:-->
         <type></type>
         <!--Optional:-->
         <terr>44</terr>
         <!--Optional:-->
         <maximumResponses>3</maximumResponses>
      </sch:autocompleteV2>
   </soapenv:Body>
</soapenv:Envelope>

Response

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:autocompleteV2Response xmlns:ns2="http://geoconcept.com/gc/schemas">
         <AutoCompleteResults>
            <status>OK</status>
            <result>
               <city>NANTES</city>
               <classification>2</classification>
               <country>FR</country>
               <fulltext>RUE NOIRE, 44000 NANTES</fulltext>
               <postCode>44000</postCode>
               <street>RUE NOIRE</street>
            </result>
            <result>
               <city>BLAIN</city>
               <classification>5</classification>
               <country>FR</country>
               <fulltext>RUE NOIRE, 44130 BLAIN</fulltext>
               <postCode>44130</postCode>
               <street>RUE NOIRE</street>
            </result>
            <result>
               <city>NOTRE-DAME-DES-LANDES</city>
               <classification>7</classification>
               <country>FR</country>
               <fulltext>RUE NOIRE, 44130 NOTRE-DAME-DES-LANDES</fulltext>
               <postCode>44130</postCode>
               <street>RUE NOIRE</street>
            </result>
         </AutoCompleteResults>
      </ns2:autocompleteV2Response>
   </soap:Body>
</soap:Envelope>

REST

Query

JSON query

http://<server>/<webapp>/api/lbs/autocomplete.json?text=rue%20noire&terr=44&maximumResponses=3

JSON-P query

http://<server>/<webapp>/api/lbs/autocomplete.json?text=rue%20noire&terr=44&maximumResponses=3&callback=myFonction

XML query

http://<server>/<webapp>/api/lbs/autocomplete.xml?text=rue%20noire&terr=44&maximumResponses=3

Response

The response is always in UTF-8 format.

JSON format

{
   "message":null,
   "status":"OK",
   "results":[
      {
         "fulltext":"RUE NOIRE, 44000 NANTES",
         "country":"FR",
         "classification":2,
         "street":"RUE NOIRE",
         "city":"NANTES",
         "zipcode":"44000"
      },
      {
         "fulltext":"RUE NOIRE, 44130 BLAIN",
         "country":"FR",
         "classification":5,
         "street":"RUE NOIRE",
         "city":"BLAIN",
         "zipcode":"44130"
      },
      {
         "fulltext":"RUE NOIRE, 44130 NOTRE-DAME-DES-LANDES",
         "country":"FR",
         "classification":7,
         "street":"RUE NOIRE",
         "city":"NOTRE-DAME-DES-LANDES",
         "zipcode":"44130"
      }
   ]
}

JSON-P format

myFonction(
    {
   "message":null,
   "status":"OK",
   "results":[
      {
         "fulltext":"RUE NOIRE, 44000 NANTES",
         "country":"FR",
         "classification":2,
         "street":"RUE NOIRE",
         "city":"NANTES",
         "zipcode":"44000"
      },
      {
         "fulltext":"RUE NOIRE, 44130 BLAIN",
         "country":"FR",
         "classification":5,
         "street":"RUE NOIRE",
         "city":"BLAIN",
         "zipcode":"44130"
      },
      {
         "fulltext":"RUE NOIRE, 44130 NOTRE-DAME-DES-LANDES",
         "country":"FR",
         "classification":7,
         "street":"RUE NOIRE",
         "city":"NOTRE-DAME-DES-LANDES",
         "zipcode":"44130"
      }
   ]
}
);

XML format

<?xml version="1.0" encoding="UTF-8"?>
<autoCompleteResults>
   <status>OK</status>
   <result>
      <city>NANTES</city>
      <classification>2</classification>
      <country>FR</country>
      <fulltext>RUE NOIRE, 44000 NANTES</fulltext>
      <street>RUE NOIRE</street>
      <zipcode>44000</zipcode>
   </result>
   <result>
      <city>BLAIN</city>
      <classification>5</classification>
      <country>FR</country>
      <fulltext>RUE NOIRE, 44130 BLAIN</fulltext>
      <street>RUE NOIRE</street>
      <zipcode>44130</zipcode>
   </result>
   <result>
      <city>NOTRE-DAME-DES-LANDES</city>
      <classification>7</classification>
      <country>FR</country>
      <fulltext>RUE NOIRE, 44130 NOTRE-DAME-DES-LANDES</fulltext>
      <street>RUE NOIRE</street>
      <zipcode>44130</zipcode>
   </result>
</autoCompleteResults>

Possible responses

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

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:autocompleteV2Response xmlns:ns2="http://geoconcept.com/gc/schemas">
         <AutoCompleteResults>
            <status>OK</status>
            <result>
               <city>NANTES</city>
               <classification>2</classification>
               <country>FR</country>
               <fulltext>RUE NOIRE, 44000 NANTES</fulltext>
               <postCode>44000</postCode>
               <street>RUE NOIRE</street>
            </result>
            <result>
               <city>BLAIN</city>
               <classification>5</classification>
               <country>FR</country>
               <fulltext>RUE NOIRE, 44130 BLAIN</fulltext>
               <postCode>44130</postCode>
               <street>RUE NOIRE</street>
            </result>
            <result>
               <city>NOTRE-DAME-DES-LANDES</city>
               <classification>7</classification>
               <country>FR</country>
               <fulltext>RUE NOIRE, 44130 NOTRE-DAME-DES-LANDES</fulltext>
               <postCode>44130</postCode>
               <street>RUE NOIRE</street>
            </result>
         </AutoCompleteResults>
      </ns2:autocompleteV2Response>
   </soap:Body>
</soap:Envelope>

The case of an address that does not exist (autocompleteResponse/AutoCompleteResults/status is ERROR)

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:autocompleteV2Response xmlns:ns2="http://geoconcept.com/gc/schemas">
         <AutoCompleteResults>
            <status>ERROR</status>
         </AutoCompleteResults>
      </ns2:autocompleteV2Response>
   </soap:Body>
</soap:Envelope>

The case of a query having an XML error or not respecting the WSDL ⇒ error with faultstring that contains the description

<soap:Fault>
        <faultcode xmlns:ns1="geoconcept.com">ns1:8</faultcode>
        <faultstring>Message part {http://geoconcept.com/gc/schemas}geocodeABCD was not recognized.  (Does it exist in service WSDL?)</faultstring>
</soap:Fault>

The case of a query with a non-existant territory (autocompleteResponse/AutoCompleteResults/status est ERROR)

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:autocompleteResponse xmlns:ns2="http://geoconcept.com/gc/schemas">
         <AutoCompleteResults>
            <status>ERROR</status>
         </AutoCompleteResults>
      </ns2:autocompleteResponse>
   </soap:Body>
</soap:Envelope>

The case of a maximum number of responses query with an input error. For example, putting a number with a comma in it, or any other character. The value entered in the Designer Administration is the one that will be used in priority cf. Geoconcept Web / Administration / Parameters geocoder.maxCandidates

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:autocompleteResponse xmlns:ns2="http://geoconcept.com/gc/schemas">
         <AutoCompleteResults>
            <status>OK</status>
            <result>
               <city>PARIS</city>
               <classification>1</classification>
               <country>FR</country>
               <fulltext>AVENUE DU GÉNÉRAL BALFOURIER, 75016 PARIS</fulltext>
               <kind/>
               <street>AVENUE DU GÉNÉRAL BALFOURIER</street>
               <x>0.0</x>
               <y>0.0</y>
               <postCode>75016</postCode>
            </result>
         </AutoCompleteResults>
      </ns2:autocompleteResponse>
   </soap:Body>
</soap:Envelope>

V1

Parameters / properties

Input

parameter	description	optional	default
text	Location address to enter	yes
type	Allows selection of the source of the autocomplete files indicating the alias for the latter: if a single autocomplete source exists, the value should remain empty if several sources exist for the autocomplete function, you will need to use the aliases of the latter, defined beforehand cf. Geoconcept Web / Administration / Parameters `geocoder.autocomplete.alias.<alias_name>.datasource` the value of this key must indicate the name of the directory containing the series of files needed for autocompletion.	yes
terr	Filter on the territory where one wants to search for the localising elements in question. example, if you want the query to apply to a town, it will be necessary to enter a postcode : 92220 if you want the search to be applied to several towns or departments, you need to separate the territories with a “;” : 75;78;92 if the value remains empty, the search will be applied to all of the territory covered by the autocomplete files and the results will be sorted in increasing streets alphabetical order.	yes
maximumResponses	maximum number of results for addresses in the response. if the value is left empty, the parameter defined in the Administration will apply	yes	cf. Geoconcept Web / Administration / Parameters `geocoder.maxCandidates`

As output

property	type	min/max	description
city	string	0/1	town found
classification	integer	1/1	code indicating in which category the town returned is found by the webservice. example, the categorisation of HERE tables ranges from 1 (the biggest towns) to 8 (village or hamlet)
country	string	0/1	country on two letters (ISO code 3166-1 or ccTLD) for example "fr" when the result is found in France
fulltext	string	0/1	street found with a specific nomenclature including the post code and the name of the town
street	string	1/1	street found
zipcode	string	0/1	post code found

SOAP

WSDL

http://<server>/<webapp>/api/ws/autoCompleteService?wsdl

Query

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sch="http://geoconcept.com/gc/schemas">
   <soapenv:Header/>
   <soapenv:Body>
      <sch:autocomplete>
         <!--Optional:-->
         <text>Avenue Général</text>
         <!--Optional:-->
         <type></type>
         <!--Optional:-->
         <terr>75</terr>
         <!--Optional:-->
         <maximumResponses>3</maximumResponses>
         <!--Optional:-->
         <repeat>?</repeat>
      </sch:autocomplete>
   </soapenv:Body>
</soapenv:Envelope>

Response

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:autocompleteResponse xmlns:ns2="http://geoconcept.com/gc/schemas">
         <AutoCompleteResults>
            <status>OK</status>
            <result>
               <city>PARIS</city>
               <classification>1</classification>
               <country>FR</country>
               <fulltext>AVENUE DU GÉNÉRAL BALFOURIER, 75016 PARIS</fulltext>
               <kind/>
               <street>AVENUE DU GÉNÉRAL BALFOURIER</street>
               <x>0.0</x>
               <y>0.0</y>
               <zipcode>75016</zipcode>
            </result>
            <result>
               <city>PARIS</city>
               <classification>1</classification>
               <country>FR</country>
               <fulltext>AVENUE DU GÉNÉRAL CLAVERY, 75016 PARIS</fulltext>
               <kind/>
               <street>AVENUE DU GÉNÉRAL CLAVERY</street>
               <x>0.0</x>
               <y>0.0</y>
               <zipcode>75016</zipcode>
            </result>
            <result>
               <city>PARIS</city>
               <classification>1</classification>
               <country>FR</country>
               <fulltext>AVENUE DU GÉNÉRAL DÉTRIE, 75007 PARIS</fulltext>
               <kind/>
               <street>AVENUE DU GÉNÉRAL DÉTRIE</street>
               <x>0.0</x>
               <y>0.0</y>
               <zipcode>75007</zipcode>
            </result>
         </AutoCompleteResults>
      </ns2:autocompleteResponse>
   </soap:Body>
</soap:Envelope>

REST

Query

JSON query

http://<server>/<webapp>/api/lbs/autocomplete.json?text=rue%20general&terr=75&maximumResponses=3

JSON-P query

http://<server>/<webapp>/api/lbs/autocomplete.json?text=rue%20general&terr=75&maximumResponses=3&callback=myFonction

XML query

http://<server>/<webapp>/api/lbs/autocomplete.xml?text=rue%20general&terr=75&maximumResponses=3

Response

The response is always in UTF-8 format.

JSON format

{
   "message": null,
   "status": "OK",
   "results":    [
            {
         "fulltext": "RUE DU GÉNÉRAL ANSELIN, 75016 PARIS",
         "country": "FR",
         "classification": 1,
         "street": "RUE DU GÉNÉRAL ANSELIN",
         "city": "PARIS",
         "zipcode": "75016",
         "x": 0,
         "y": 0,
         "kind": ""
      },
            {
         "fulltext": "RUE DU GÉNÉRAL ANSELIN, 75116 PARIS",
         "country": "FR",
         "classification": 1,
         "street": "RUE DU GÉNÉRAL ANSELIN",
         "city": "PARIS",
         "zipcode": "75116",
         "x": 0,
         "y": 0,
         "kind": ""
      },
            {
         "fulltext": "RUE DU GÉNÉRAL APPERT, 75116 PARIS",
         "country": "FR",
         "classification": 1,
         "street": "RUE DU GÉNÉRAL APPERT",
         "city": "PARIS",
         "zipcode": "75116",
         "x": 0,
         "y": 0,
         "kind": ""
      }
   ]
}

JSON-P format

myFonction({
        "message":null,"status":"OK",
"results":[
                {
                        "fulltext":"RUE DU GÉNÉRAL ANSELIN, 75016 PARIS","country":"FR","classification":1,"street":"RUE DU GÉNÉRAL ANSELIN","city":"PARIS","zipcode":"75016","x":0.0,"y":0.0,"kind":""
                },
                {
                        "fulltext":"RUE DU GÉNÉRAL ANSELIN, 75116 PARIS","country":"FR","classification":1,"street":"RUE DU GÉNÉRAL ANSELIN","city":"PARIS","zipcode":"75116","x":0.0,"y":0.0,"kind":""
                },
                {
                        "fulltext":"RUE DU GÉNÉRAL APPERT, 75116 PARIS","country":"FR","classification":1,"street":"RUE DU GÉNÉRAL APPERT","city":"PARIS","zipcode":"75116","x":0.0,"y":0.0,"kind":""}
]});

XML format

<autoCompleteResults>
   <status>OK</status>
   <result>
      <city>PARIS</city>
      <classification>1</classification>
      <country>FR</country>
      <fulltext>RUE DU GÉNÉRAL ANSELIN, 75016 PARIS</fulltext>
      <kind/>
      <street>RUE DU GÉNÉRAL ANSELIN</street>
      <x>0.0</x>
      <y>0.0</y>
      <zipcode>75016</zipcode>
   </result>
   <result>
      <city>PARIS</city>
      <classification>1</classification>
      <country>FR</country>
      <fulltext>RUE DU GÉNÉRAL ANSELIN, 75116 PARIS</fulltext>
      <kind/>
      <street>RUE DU GÉNÉRAL ANSELIN</street>
      <x>0.0</x>
      <y>0.0</y>
      <zipcode>75116</zipcode>
   </result>
   <result>
      <city>PARIS</city>
      <classification>1</classification>
      <country>FR</country>
      <fulltext>RUE DU GÉNÉRAL APPERT, 75116 PARIS</fulltext>
      <kind/>
      <street>RUE DU GÉNÉRAL APPERT</street>
      <x>0.0</x>
      <y>0.0</y>
      <zipcode>75116</zipcode>
   </result>
</autoCompleteResults>

Possible responses

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

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:autocompleteResponse xmlns:ns2="http://geoconcept.com/gc/schemas">
         <AutoCompleteResults>
            <status>OK</status>
            <result>
               <city>PARIS</city>
               <classification>1</classification>
               <country>FR</country>
               <fulltext>AVENUE DU GÉNÉRAL BALFOURIER, 75016 PARIS</fulltext>
               <kind/>
               <street>AVENUE DU GÉNÉRAL BALFOURIER</street>
               <x>0.0</x>
               <y>0.0</y>
               <zipcode>75016</zipcode>
            </result>
            <result>
               <city>PARIS</city>
               <classification>1</classification>
               <country>FR</country>
               <fulltext>AVENUE DU GÉNÉRAL CLAVERY, 75016 PARIS</fulltext>
               <kind/>
               <street>AVENUE DU GÉNÉRAL CLAVERY</street>
               <x>0.0</x>
               <y>0.0</y>
               <zipcode>75016</zipcode>
            </result>
            <result>
               <city>PARIS</city>
               <classification>1</classification>
               <country>FR</country>
               <fulltext>AVENUE DU GÉNÉRAL DÉTRIE, 75007 PARIS</fulltext>
               <kind/>
               <street>AVENUE DU GÉNÉRAL DÉTRIE</street>
               <x>0.0</x>
               <y>0.0</y>
               <zipcode>75007</zipcode>
            </result>
         </AutoCompleteResults>
      </ns2:autocompleteResponse>
   </soap:Body>
</soap:Envelope>

The case of an address that does not exist (autocompleteResponse/AutoCompleteResults/status is ERROR)

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:autocompleteResponse xmlns:ns2="http://geoconcept.com/gc/schemas">
         <AutoCompleteResults>
            <status>ERROR</status>
         </AutoCompleteResults>
      </ns2:autocompleteResponse>
   </soap:Body>
</soap:Envelope>

The case of a query having an XML error or not respecting the WSDL ⇒ error with faultstring that contains the description

<soap:Fault>
        <faultcode xmlns:ns1="geoconcept.com">ns1:8</faultcode>
        <faultstring>Message part {http://geoconcept.com/gc/schemas}geocodeABCD was not recognized.  (Does it exist in service WSDL?)</faultstring>
</soap:Fault>

The case of a query with a non-existant territory (autocompleteResponse/AutoCompleteResults/status est ERROR)

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:autocompleteResponse xmlns:ns2="http://geoconcept.com/gc/schemas">
         <AutoCompleteResults>
            <status>ERROR</status>
         </AutoCompleteResults>
      </ns2:autocompleteResponse>
   </soap:Body>
</soap:Envelope>

The case of a maximum number of responses query with an input error. For example, putting a number with a comma in it, or any other character. The value entered in the Designer Administration is the one that will be used in priority cf. Geoconcept Web / Administration / Parameters geocoder.maxCandidates

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:autocompleteResponse xmlns:ns2="http://geoconcept.com/gc/schemas">
         <AutoCompleteResults>
            <status>OK</status>
            <result>
               <city>PARIS</city>
               <classification>1</classification>
               <country>FR</country>
               <fulltext>AVENUE DU GÉNÉRAL BALFOURIER, 75016 PARIS</fulltext>
               <kind/>
               <street>AVENUE DU GÉNÉRAL BALFOURIER</street>
               <x>0.0</x>
               <y>0.0</y>
               <zipcode>75016</zipcode>
            </result>
         </AutoCompleteResults>
      </ns2:autocompleteResponse>
   </soap:Body>
</soap:Envelope>

Prev	Up	Next
	Home

Web Services documentation of Geoconcept Web - Web Services

Basic principles

Availability

Version change

V2

Parameters / properties

SOAP

REST

Possible responses

V1

Parameters / properties

SOAP

REST

Possible responses