Ce service de complétion automatique, ou autocomplétion, a pour but de faire gagner du temps à l’internaute qui saisit un localisant. Il propose des localisants probables au fur et à mesure qu’un internaute tape les lettres d’une adresse ou d’un lieu-dit, ou les efface, dans le champ de saisie du localisant.
exemple : l’internaute rentre « avenue des cham », le service renvoie « Avenue des Champs-Élysées, Paris », ainsi que d’autres localisants commençant par la même chaîne.
Ce service prend en entrée une chaîne de caractère, en option un identifiant de territoire, et un identifiant de type d’entité recherchée. A partir d’index optimisés, il est capable de fournir instantanément un extrait des localisants (adresses) commençant par cette chaîne, dans ce territoire, et de ce type.
Les localisants sont classés dans les fichiers de référence par un poids permettant de présenter d’abord les plus probables en prennant en compte la taille de la ville.
Il est nécessaire de copier des fichiers de référence et de configurer le service grâce à l’interface Administration de Geoconcept Web, voir le chapitre Installation de Geoconcept Web / Paramètres / Paramétrages de UGC / Web service d’autocomplétion.
Avertissement | |
---|---|
Ce web service ne fait pas d’opération de géocodage. Le web service de géocodage peut être utilisé avec les données reçues du service d’autocomplétion en prenant l’adresse trouvée par le module d’autocomplétion comme paramètre d’entrée du geocoder. Pour une optimisation des performances, nous préconisons de construire le géocodage du résultat de l’autocomplétion avec des champs séparés, et non à partir du champ fulltext (les deux sont fournis dans le résultat de l’autocomplétion). |
Astuce | |
---|---|
Nous préconisons une architecture 64 bits d’UGC Server car l’autocomplétion nécessite des ressources importantes. |
Pour des raisons de performance, (le service devant être appelé à chaque frappe de l’internaute), il sera publié sous forme de service JSON. En option, il pourra également être appelé sous forme de service JSON-P.
Ce web service est disponible en permanence avec Geoconcept Web avec les fichiers de référence.
Les versions précédente du web service sont conservées dans Geoconcept Web pour assurer la compatibilité avec les développements antérieurs. Il est recommandé d’utiliser la version la plus récente.
Changements avec la v2
- Le paramètre "zipcode" est renommé "postCode"
En entrée
paramètre | description | optionnel | défaut |
---|---|---|---|
text |
Localisant à saisir |
oui |
|
type |
Permet de choisir la source de fichiers d’autocomplétion en indiquant l’alias de cette dernière : |
oui |
|
terr |
Filtre sur le territoire où l’on veut rechercher les localisants en question. |
oui |
|
maximumResponses |
nombre maximum de résultats d’adresses dans la réponse. |
oui |
cf. Geoconcept Web / Administration / Paramètres |
En sortie
propriété | type | min/max | description |
---|---|---|---|
city |
string |
0/1 |
ville trouvée |
classification |
integer |
1/1 |
code indiquant dans quelle catégorie se trouve la ville retournée par le webservice. |
country |
string |
0/1 |
pays sur deux lettres (code ISO 3166-1 ou ccTLD) par exemple "fr" lorsque le résultat est trouvé en France |
fulltext |
string |
0/1 |
rue trouvée avec une nomenclature spécifique incluant le code postal et le nom de la ville |
street |
string |
1/1 |
rue trouvée |
postCode |
string |
0/1 |
code postal trouvé |
WSDL
http://<server>
/<webapp>
/api/ws/autoCompleteService?wsdl
Requête
<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>
Réponse
<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>
Requête
Requête JSON
http://<server>/<webapp>/api/lbs/autocomplete.json?text=rue%20noire&terr=44&maximumResponses=3
Requête JSON-P
http://<server>/<webapp>/api/lbs/autocomplete.json?text=rue%20noire&terr=44&maximumResponses=3&callback=myFonction
Requête XML
http://<server>/<webapp>/api/lbs/autocomplete.xml?text=rue%20noire&terr=44&maximumResponses=3
Réponse
La réponse est toujours encodée en UTF-8.
Format JSON
{ "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" } ] }
Format JSON-P
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" } ] } );
Format XML
<?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>
Cas d’addresses trouvées (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>
Cas d’une adresse qui n’existe pas (autocompleteResponse/AutoCompleteResults/status est 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>
Cas d’une requête ayant une erreur XML ou ne respectant pas le WSDL ⇒ erreur avec faultstring qui contient la 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>
Cas d’une requête avec un territoire inexistant (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>
Cas d’une requête un nombre maximum de réponse qui est mal renseigné. Par exemple, mettre un nombre à virgule ou tout autre
caractère. C’est la valeur renseignée dans l’Adminitration qui prend alors le dessus cf. Geoconcept Web / Administration /
Paramètres 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>
En entrée
paramètre | description | optionnel | défaut |
---|---|---|---|
text |
Localisant à saisir |
oui |
|
type |
Permet de choisir la source de fichiers d’autocomplétion en indiquant l’alias de cette dernière : |
oui |
|
terr |
Filtre sur le territoire où l’on veut rechercher les localisants en question. |
oui |
|
maximumResponses |
nombre maximum de résultats d’adresses dans la réponse. |
oui |
cf. Geoconcept Web / Administration / Paramètres |
En sortie
propriété | type | min/max | description |
---|---|---|---|
city |
string |
0/1 |
ville trouvée |
classification |
integer |
1/1 |
code indiquant dans quelle catégorie se trouve la ville retournée par le webservice. |
country |
string |
0/1 |
pays sur deux lettres (code ISO 3166-1 ou ccTLD) par exemple "fr" lorsque le résultat est trouvé en France |
fulltext |
string |
0/1 |
rue trouvée avec une nomenclature spécifique incluant le code postal et le nom de la ville |
street |
string |
1/1 |
rue trouvée |
zipcode |
string |
0/1 |
code postal trouvé |
WSDL
http://<server>
/<webapp>
/api/ws/autoCompleteService?wsdl
Requête
<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>
Réponse
<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>
Requête
Requête JSON
http://<server>/<webapp>/api/lbs/autocomplete.json?text=rue%20general&terr=75&maximumResponses=3
Requête JSON-P
http://<server>/<webapp>/api/lbs/autocomplete.json?text=rue%20general&terr=75&maximumResponses=3&callback=myFonction
Requête XML
http://<server>/<webapp>/api/lbs/autocomplete.xml?text=rue%20general&terr=75&maximumResponses=3
Réponse
La réponse est toujours encodée en UTF-8.
Format JSON
{ "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": "" } ] }
Format JSON-P
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":""} ]});
Format XML
<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>
Cas d’addresses trouvées (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>
Cas d’une adresse qui n’existe pas (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>
Cas d’une requête ayant une erreur XML ou ne respectant pas le WSDL ⇒ erreur avec faultstring qui contient la 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>
Cas d’une requête avec un territoire inexistant (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>
Cas d’une requête un nombre maximum de réponse qui est mal renseigné. Par exemple, mettre un nombre à virgule ou tout autre
caractère. C’est la valeur renseignée dans l’Adminitration qui prend alors le dessus cf. Geoconcept Web / Administration /
Paramètres 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>