Geocoding

(fr) Cette page n’est plus maintenue depuis la version 2022 de Geoconcept Web. Pour accéder à la documentation à jour de ce web service, veuillez suivre ce lien.

Basic principles

The query includes an input address, the service returns one or several possible responses (if there is any ambiguity), including the recognised address, the position, the geocoding score, and the geocoding type.

This geocoding service consults the reference table configured via the Administration interface of Geoconcept Web.

Availability

This web service is available at all times with Geoconcept Web and a reference table.

Version change

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

Changes in relation to v2

Deletion of the "projection" parameter, replaced by "srs"
Deletion of the "geocodeScore" parameter, replaced by "score"
Deletion of "projection", "srs" and "maxResponses" parameters in the "initialAddress" block
The "postalCode" parameter has been renamed "postCode"

V2

Parameters / properties

Input

parameter	description	optional	default
countryCode	countries on two or three letters (ISO code 3166-1 or ccTLD) for example, "fr" or"fra", this parameter can be used to distinguish between several repositories for a single territory (IGN, HERE, …)	yes	cf. Geoconcept Web / Administration / Parameters `geocoder.datasource`
postCode	post code	yes *
addressLine	address including number, repetition index, type of street and street name.	yes *
city	city	yes *
region	State, County, …	yes
srs	projection (EPSG code such as epsg:4326 or wgs84)	yes	Without any projection, the result is in the native projection of the geocoding index, which is usually wgs84
maxResponses	maximum number of address results in the response	yes	cf. Geoconcept Web / Administration / Parameters `geocoder.maxCandidates`
streetMinScore	the value of this parameters varies, as for the score, between 0 and 100. The streetMinScore has the effect of filtering possible candidates in the following way: If the candidate score is equal to or higher than the score, the candidate is selected as it is, If the candidate score is lower than the score and no candidate match has already been selected, the geocoding is suggested at town level, If the candidate score is lower than the score, and another candidate has already been selected, then the candidate will not be presented unless it fulfills the condition of the parameter `geocoder.maxCandidates` The value of streetMinScore must always be higher than `filterMinScore`, if this is not the case, the geocoding forces the value of `filterMinScore` for streetMinScore. The value defined for streetMinScore replaces that defined in the `geocoder.geocoder.streetMinScore` paremeter. The `geocoder.maxCandidates` and `geocoder.minscore` parameters are described in Geoconcept Web / Administration / Parameters.	yes

(*) At least one of the three parameters postCode, addressLine and city must be assigned a value.

Output

parameter	type	min/max	description
geocodedAddress (or geocodedAddresses in JSON / JSON-P)	geocodedAddress (or array in JSON / JSON-P)	0/unlimited	Geocoded addresses
initialAddress	geocodeInitialAddress	0/1	Initial address

Geocoded addresses (geocodedAddress)

parameter	type	min/max	description
addressLine	string	0/1	street found and, if there is one, the number
city	string	0/1	town found
region	string	0/1	State, County, ..; found, varies as a function of country, can also be empty
countryCode	string	1/1	cf. description of the input parameter
postCode	string	0/1	post code found
secondaryZone	string	0/1	zone that depends on the geocoding index, usually in France this will be an IRIS code
score	double	1/1	geocoding score from 0 to 100, with 100 for a perfect correspondance
geocodeType	int	1/1	type of geocoding: - town = 1 - street = 2 - improved street = 3 - street number = 4 - non-geocoded = 0
x	double	1/1	X coordinates
y	double	1/1	Y coordinates
place (or places in JSON / JSON-P)	string (or array in JSON / JSON-P)	0/unlimited	list of attributes. Value of attributes for the address found, in relation to placeTypes (for example ["751010206","930005Y001XCHE"]). Depends on the repository used.
placeType (or placeTypes en JSON / JSON-P)	string (or array in JSON / JSON-P)	0/unlimited	list of types of attributes (for example ["IRIS","FANTOIR"]). Depends on the reference table used.
streetNumber	string	0/1	street number
streetWayType	string	0/1	type of street (avenue, street, etc)
streetWayName	string	0/1	street name
streetWay	string	0/1	full name of the street

Initial address (initialAddress)

parameter	type	min/max	description
addressLine	string	0/1	street found and, if there is one, the number
city	string	0/1	town found
region	string	0/1	State, County, ..; found, varies as a function of country, can also be empty
countryCode	string	1/1	cf. description of the input parameter
postCode	string	0/1	post code found

SOAP

WSDL

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

Query

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sch="http://geoconcept.com/gc/schemas">
   <soapenv:Header/>
   <soapenv:Body>
      <sch:geocodeV2>
         <!--Optional:-->
         <countryCode>FR</countryCode>
         <!--Optional:-->
         <postCode>44000</postCode>
         <!--Optional:-->
         <addressLine>45 Rue Noire</addressLine>
         <!--Optional:-->
         <city>nantes</city>
         <!--Optional:-->
         <region></region>
         <!--Optional:-->
         <srs>epsg:4326</srs>
         <maxResponses>2</maxResponses>
         <streetMinScore></streetMinScore>
      </sch:geocodeV2>
   </soapenv:Body>
</soapenv:Envelope>

Response

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:geocodeV2Response xmlns:ns2="http://geoconcept.com/gc/schemas">
         <GeocodeResult>
            <status>OK</status>
            <geocodedAddress>
               <addressLine>45 RUE NOIRE</addressLine>
               <city>Nantes</city>
               <countryCode>FR</countryCode>
               <postCode>44109</postCode>
               <srs>epsg:4326</srs>
               <secondaryZone/>
               <score>94.95</score>
               <geocodeType>4</geocodeType>
               <x>-1.563901</x>
               <y>47.224987</y>
               <places>
                  <place/>
               </places>
               <placeTypes>
                  <placeType>Attribut</placeType>
               </placeTypes>
               <streetNumber>45</streetNumber>
               <streetWayType>RUE</streetWayType>
               <streetWayName>NOIRE</streetWayName>
               <streetWay>RUE NOIRE</streetWay>
            </geocodedAddress>
            <initialAddress>
               <addressLine>45 Rue Noire</addressLine>
               <city>nantes</city>
               <region/>
               <countryCode>FR</countryCode>
               <postCode>44000</postCode>
            </initialAddress>
         </GeocodeResult>
      </ns2:geocodeV2Response>
   </soap:Body>
</soap:Envelope>

REST

Query

JSON query

http://<server>/<webapp>/api/lbs/geocode/v2.json?addressLine=45%20Rue%20Noire&postCode=44000&city=nantes&countryCode=fr&srs=epsg:4326

JSON-P query

http://<server>/<webapp>/api/lbs/geocode/v2.json?addressLine=45%20Rue%20Noire&postCode=44000&city=nantes&countryCode=fr&srs=epsg:4326&callback=myCallback

XML query

http://<server>/<webapp>/api/lbs/geocode/v2.xml?addressLine=45%20Rue%20Noire&postCode=44000&city=nantes&countryCode=fr&srs=epsg:4326

Response

The response is always in UTF-8 format.

JSON format

{
   "message":null,
   "status":"OK",
   "geocodedAddresses":[
      {
         "addressLine":"45 RUE NOIRE",
         "city":"Nantes",
         "countryCode":"FR",
         "postCode":"44109",
         "srs":"epsg:4326",
         "secondaryZone":"",
         "score":94.95,
         "geocodeType":4,
         "x":-1.563901,
         "y":47.224987,
         "places":[
            ""
         ],
         "placeTypes":[
            "Attribut"
         ],
         "streetNumber":"45",
         "streetWayType":"RUE",
         "streetWayName":"NOIRE",
         "streetWay":"RUE NOIRE"
      }
   ],
   "initialAddress":{
      "addressLine":"45 Rue Noire",
      "city":"nantes",
      "countryCode":"fr",
      "postCode":"44000"
   }
}

JSON-P format

MyCallBack({
   "message":null,
   "status":"OK",
   "geocodedAddresses":[
      {
         "addressLine":"45 RUE NOIRE",
         "city":"Nantes",
         "countryCode":"FR",
         "postCode":"44109",
         "srs":"epsg:4326",
         "secondaryZone":"",
         "score":94.95,
         "geocodeType":4,
         "x":-1.563901,
         "y":47.224987,
         "places":[
            ""
         ],
         "placeTypes":[
            "Attribut"
         ],
         "streetNumber":"45",
         "streetWayType":"RUE",
         "streetWayName":"NOIRE",
         "streetWay":"RUE NOIRE"
      }
   ],
   "initialAddress":{
      "addressLine":"45 Rue Noire",
      "city":"nantes",
      "countryCode":"fr",
      "postCode":"44000"
   }
});

XML format

<?xml version="1.0" encoding="UTF-8"?>
<geocodeResultV2>
   <status>OK</status>
   <geocodedAddress>
      <addressLine>45 RUE NOIRE</addressLine>
      <city>Nantes</city>
      <countryCode>FR</countryCode>
      <postCode>44109</postCode>
      <srs>epsg:4326</srs>
      <secondaryZone />
      <score>94.95</score>
      <geocodeType>4</geocodeType>
      <x>-1.563901</x>
      <y>47.224987</y>
      <places>
         <place />
      </places>
      <placeTypes>
         <placeType>Attribut</placeType>
      </placeTypes>
      <streetNumber>45</streetNumber>
      <streetWayType>RUE</streetWayType>
      <streetWayName>NOIRE</streetWayName>
      <streetWay>RUE NOIRE</streetWay>
   </geocodedAddress>
   <initialAddress>
      <addressLine>45 Rue Noire</addressLine>
      <city>nantes</city>
      <countryCode>fr</countryCode>
      <postCode>44000</postCode>
   </initialAddress>
</geocodeResultV2>

API JavaScript

Include the Javascript library.

var geocoder = new GCUI.Control.GeoCode();
geocoder.geocode({url : 'http://<server>/<webapp>/api/lbs/geocode/v2.json', city : 'Nantes', postCode : '44000', addressLine : '45 Rue Noire', countryCode : 'fr', srs : 'wgs84',
callback : function(result) {...} }) ;

The result variable is in JSON format as described above. The callback function passed as parameter is called at the end of the geocoding operation.

Possible responses

Case of an address found (geocodeResponse/GeocodeResult/status is OK)

<ns2:geocodeV2Response xmlns:ns2="http://geoconcept.com/gc/schemas">
    <?xml version="1.0" encoding="UTF-8"?>
    <geocodeResultV2>
       <status>OK</status>
       <geocodedAddress>
          <addressLine>45 RUE NOIRE</addressLine>
          <city>Nantes</city>
          <countryCode>FR</countryCode>
          <postCode>44109</postCode>
          <srs>epsg:4326</srs>
          <secondaryZone />
          <score>94.95</score>
          <geocodeType>4</geocodeType>
          <x>-1.563901</x>
          <y>47.224987</y>
          <places>
             <place />
          </places>
          <placeTypes>
             <placeType>Attribut</placeType>
          </placeTypes>
          <streetNumber>45</streetNumber>
          <streetWayType>RUE</streetWayType>
          <streetWayName>NOIRE</streetWayName>
          <streetWay>RUE NOIRE</streetWay>
       </geocodedAddress>
       <initialAddress>
          <addressLine>45 Rue Noire</addressLine>
          <city>nantes</city>
          <countryCode>fr</countryCode>
          <postCode>44000</postCode>
       </initialAddress>
    </geocodeResultV2>
</ns2:geocodeV2Response>

Case of an address that is not found (geocodeResponse/GeocodeResult/status is OK and no geocodedAddress)

<ns2:geocodeV2Response xmlns:ns2="http://geoconcept.com/gc/schemas">
        <GeocodeResult>
                <status>OK</status>
                <initialAddress>
                        <city>#hdkvnjsdvn</city>
                </initialAddress>
        </GeocodeResult>
</ns2:geocodeV2Response>

Case of a query containing 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>

Case of a query with a non-existant reprojection system ⇒ error with faultstring that contains the description

<soap:Fault>
        <faultcode xmlns:ns1="geoconcept.com">ns1:8</faultcode>
        <faultstring>Geocode failed Failed to process geocoding task Unsupported coordinate system 'epsg:432666666'</faultstring>
</soap:Fault>

V1

Parameters / properties

Input

parameter	description	optional	default
countryCode	countries on two letters (ISO code 3166-1 or ccTLD) for example, "fr", this parameter can be used to distinguish between several repositories for a single territory (IGN, HERE, …)	yes	cf. Geoconcept Web / Administration / Parameters `geocoder.datasource`
postalCode	post code	yes *
addressLine	address including number, repetition index, type of street and street name.	yes *
city	city	yes *
region	State, County, …	yes
projection	depreciated, replaced by srs	yes
srs	projection (EPSG code such as epsg:4326 or wgs84)	yes	Without any projection, the result is in the native projection of the geocoding index, which is usually wgs84
maxResponses	maximum number of address results in the response	yes	cf. Geoconcept Web / Administration / Parameters `geocoder.maxCandidates`
streetMinScore	the value of this parameters varies, as for the score, between 0 and 100. The streetMinScore has the effect of filtering possible candidates in the following way: If the candidate score is equal to or higher than the score, the candidate is selected as it is, If the candidate score is lower than the score and no candidate match has already been selected, the geocoding is suggested at town level, If the candidate score is lower than the score, and another candidate has already been selected, then the candidate will not be presented unless it fulfills the condition of the parameter `geocoder.maxCandidates` The value of streetMinScore must always be higher than `filterMinScore`, if this is not the case, the geocoding forces the value of `filterMinScore` for streetMinScore. The value defined for streetMinScore replaces that defined in the `geocoder.geocoder.streetMinScore` paremeter. The `geocoder.maxCandidates` and `geocoder.minscore` parameters are described in Geoconcept Web / Administration / Parameters.	yes

(*) At least one of the three parameters postalCode, addressLine and city must have a value assigned.

Output

parameter	type	min/max	description
geocodedAddress (or geocodedAddresses in JSON / JSON-P)	geocodedAddress (or array in JSON / JSON-P)	0/unlimited	Geocoded addresses
initialAddress	geocodeInitialAddress	0/1	Initial address

Geocoded addresses (geocodedAddress)

parameter	type	min/max	description
secondaryZone	string	0/1	zone that depends on the geocoding index, usually in France this will be an IRIS code
score	double	1/1	geocoding score from 0 to 100, with 100 for a perfect correspondance
geocodeScore	double	1/1	Deprecated, replaced by score: geocoding score from 0 to 20, with 20 for a perfect correspondance
geocodeType	int	1/1	type of geocoding: - town = 1 - street = 2 - improved street = 3 - street number = 4 - non-geocoded = 0
x	double	1/1	X coordinates
y	double	1/1	Y coordinates
place (or places in JSON / JSON-P)	string (or array in JSON / JSON-P)	0/unlimited	list of attributes. Value of attributes for the address found, in relation to placeTypes (for example ["751010206","930005Y001XCHE"]). Depends on the repository used.
placeType (or placeTypes en JSON / JSON-P)	string (or array in JSON / JSON-P)	0/unlimited	list of types of attributes (for example ["IRIS","FANTOIR"]). Depends on the reference table used.
streetNumber	string	0/1	street number
streetWayType	string	0/1	type of street (avenue, street, etc)
streetWayName	string	0/1	street name
streetWay	string	0/1	full name of the street

Initial address (initialAddress)

parameter	type	min/max	description
addressLine	string	0/1	street found and, if there is one, the number
city	string	0/1	town found
region	string	0/1	State, County, ..; found, varies as a function of country, can also be empty
countryCode	string	1/1	cf. description of the input parameter
postalCode	string	0/1	post code found
projection	string	1/1	Deprecated, replaced by srs
srs	string	1/1	cf. description of the input parameter
maxResponses	string	0/1	cf. description of the input parameter

SOAP

WSDL

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

Query

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sch="http://geoconcept.com/gc/schemas">
   <soapenv:Header/>
   <soapenv:Body>
      <sch:geocode>
         <!--Optional:-->
         <countryCode></countryCode>
         <!--Optional:-->
         <postalCode>75013</postalCode>
         <!--Optional:-->
         <addressLine>25, rue de toldiac</addressLine>
         <!--Optional:-->
         <city>paris</city>
         <!--Optional:-->
         <region></region>
         <!--Optional:-->
         <projection></projection>
         <!--Optional:-->
         <srs></srs>
         <maxResponses>2</maxResponses>
         <streetMinScore></streetMinScore>
      </sch:geocode>
   </soapenv:Body>
</soapenv:Envelope>

Response

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:geocodeResponse xmlns:ns2="http://geoconcept.com/gc/schemas">
         <GeocodeResult>
            <status>OK</status>
            <geocodedAddress>
               <addressLine>25 RUE DE TOLBIAC</addressLine>
               <city>PARIS</city>
               <countryCode>FR</countryCode>
               <postalCode>75013</postalCode>
               <projection>epsg:27572</projection>
               <srs>epsg:27572</srs>
               <secondaryZone>751135014</secondaryZone>
               <geocodeScore>19.8101</geocodeScore>
               <score>99.05</score>
               <geocodeType>4</geocodeType>
               <x>602722.1475334</x>
               <y>2425598.4510822</y>
               <places>
                  <place>751135014</place>
               </places>
               <placeTypes>
                  <placeType>IRIS</placeType>
               </placeTypes>
               <streetNumber>25</streetNumber>
               <streetWayType>RUE</streetWayType>
               <streetWayName>DE TOLBIAC</streetWayName>
               <streetWay>RUE DE TOLBIAC</streetWay>
            </geocodedAddress>
            <geocodedAddress>
               <addressLine>PONT DE TOLBIAC</addressLine>
               <city>PARIS</city>
               <countryCode>FR</countryCode>
               <postalCode>75013</postalCode>
               <projection>epsg:27572</projection>
               <srs>epsg:27572</srs>
               <secondaryZone>751135099</secondaryZone>
               <geocodeScore>19.0505</geocodeScore>
               <score>95.25</score>
               <geocodeType>2</geocodeType>
               <x>603221.0049634</x>
               <y>2426021.5068995</y>
               <places>
                  <place>751135099</place>
               </places>
               <placeTypes>
                  <placeType>IRIS</placeType>
               </placeTypes>
               <streetNumber/>
               <streetWayType>PONT</streetWayType>
               <streetWayName>DE TOLBIAC</streetWayName>
               <streetWay>PONT DE TOLBIAC</streetWay>
            </geocodedAddress>
            <initialAddress>
               <addressLine>25, rue de toldiac</addressLine>
               <city>paris</city>
               <region/>
               <countryCode/>
               <postalCode>75013</postalCode>
               <projection/>
               <srs/>
            </initialAddress>
         </GeocodeResult>
      </ns2:geocodeResponse>
   </soap:Body>
</soap:Envelope>

REST

Query

JSON query

http://<server>/<webapp>/api/lbs/geocode.json?countryCode=fr&addressLine=25%20rue%20de%20toldiac&postalCode=75013&city=Paris&srs=epsg:4326&maxResponses=2

JSON-P query

http://<server>/<webapp>/api/lbs/geocode.json?countryCode=fr&addressLine=25%20rue%20de%20toldiac&postalCode=75013&city=Paris&srs=epsg:4326&maxResponses=2&callback=myCallback

XML query

http://<server>/<webapp>/api/lbs/geocode.xml?countryCode=fr&addressLine=25%20rue%20de%20toldiac&postalCode=75013&city=Paris&maxResponses=2

Response

The response is always in UTF-8 format.

JSON format

{
        "message":null,"status":"OK",
        "geocodedAddresses":    [
                {
                        "addressLine":"25 RUE DE TOLBIAC","city":"PARIS","countryCode":"FR","postalCode":"75013",
                        "projection":"epsg:4326","srs":"epsg:4326","maxResponses":null,"secondaryZone":"751135014",
                        "geocodeScore":19.8101,"score":99.05,"geocodeType":4,"x":2.373562,"y":48.828757,
                        "places":["751135014"],"placeTypes":["IRIS"],
                        "streetNumber":"25","streetWayType":"RUE","streetWayName":"DE TOLBIAC","streetWay":"RUE DE TOLBIAC"
                },
                {
                        "addressLine":"PONT DE TOLBIAC","city":"PARIS","countryCode":"FR","postalCode":"75013",
                        "projection":"epsg:4326","srs":"epsg:4326","maxResponses":null,"secondaryZone":"751135099",
                        "geocodeScore":19.0505,"score":95.25,"geocodeType":2,"x":2.380356,"y":48.832557,
                        "places":["751135099"],"placeTypes":["IRIS"],
                        "streetNumber":"","streetWayType":"PONT","streetWayName":"DE TOLBIAC","streetWay":"PONT DE TOLBIAC"
                }
        ],
        "initialAddress":               {
                "addressLine":"25 rue de toldiac","city":"Paris","countryCode":"fr","postalCode":"75013",
                "projection":"epsg:4326","srs":"epsg:4326"
        }
}

JSON-P format

myCallback({
        "message":null,"status":"OK",
        "geocodedAddresses":    [
                {
                        "addressLine":"25 RUE DE TOLBIAC","city":"PARIS","countryCode":"FR","postalCode":"75013",
                        "projection":"epsg:4326","srs":"epsg:4326","maxResponses":null,"secondaryZone":"751135014",
                        "geocodeScore":19.8101,"score":99.05,"geocodeType":4,"x":2.373562,"y":48.828757,
                        "places":["751135014"],"placeTypes":["IRIS"],
                        "streetNumber":"25","streetWayType":"RUE","streetWayName":"DE TOLBIAC","streetWay":"RUE DE TOLBIAC"
                },
                {
                        "addressLine":"PONT DE TOLBIAC","city":"PARIS","countryCode":"FR","postalCode":"75013",
                        "projection":"epsg:4326","srs":"epsg:4326","maxResponses":null,"secondaryZone":"751135099",
                        "geocodeScore":19.0505,"score":95.25,"geocodeType":2,"x":2.380356,"y":48.832557,
                        "places":["751135099"],"placeTypes":["IRIS"],
                        "streetNumber":"","streetWayType":"PONT","streetWayName":"DE TOLBIAC","streetWay":"PONT DE TOLBIAC"
                }
        ]
        "initialAddress":       {
                "addressLine":"25 rue de toldiac","city":"Paris","countryCode":"fr","postalCode":"75013",
                "projection":"epsg:4326","srs":"epsg:4326"
        }
});

XML format

<geocodeResult>
        <status>OK</status>
        <geocodedAddress>
                <addressLine>25 RUE DE TOLBIAC</addressLine>
                <city>PARIS</city>
                <countryCode>FR</countryCode>
                <postalCode>75013</postalCode>
                <projection>epsg:27572</projection>
                <srs>epsg:27572</srs>
                <secondaryZone>751135014</secondaryZone>
                <geocodeScore>19.8101</geocodeScore>
                <score>99.05</score>
                <geocodeType>4</geocodeType>
                <x>602722.1475334</x>
                <y>2425598.4510822</y>
                <places>
                        <place>751135014</place>
                </places>
                <placeTypes>
                        <placeType>IRIS</placeType>
                </placeTypes>
                <streetNumber>25</streetNumber>
                <streetWayType>RUE</streetWayType>
                <streetWayName>DE TOLBIAC</streetWayName>
                <streetWay>RUE DE TOLBIAC</streetWay>
        </geocodedAddress>
        <geocodedAddress>
                <addressLine>PONT DE TOLBIAC</addressLine>
                <city>PARIS</city>
                <countryCode>FR</countryCode>
                <postalCode>75013</postalCode>
                <projection>epsg:27572</projection>
                <srs>epsg:27572</srs>
                <secondaryZone>751135099</secondaryZone>
                <geocodeScore>19.0505</geocodeScore>
                <score>95.25</score>
                <geocodeType>2</geocodeType>
                <x>603221.0049634</x>
                <y>2426021.5068995</y>
                <places>
                        <place>751135099</place>
                </places>
                <placeTypes>
                        <placeType>IRIS</placeType>
                </placeTypes>
                <streetNumber/>
                <streetWayType>PONT</streetWayType>
                <streetWayName>DE TOLBIAC</streetWayName>
                <streetWay>PONT DE TOLBIAC</streetWay>
        </geocodedAddress>
        <initialAddress>
                <addressLine>25 rue de toldiac</addressLine>
                <city>Paris</city>
                <countryCode>fr</countryCode>
                <postalCode>75013</postalCode>
        </initialAddress>
</geocodeResult>

API JavaScript

Include the Javascript library.

var geocoder = new GCUI.Control.GeoCode();
geocoder.geocode({url : 'http://<server>/<webapp>/api/lbs/geocode.json', city : 'Paris', postalCode : '75013', addressLine : '25 rue de Toldiac', countryCode : 'fr', srs : 'wgs84',
callback : function(result) {...} }) ;

The result variable is in JSON format as described above. The callback function passed as parameter is called at the end of the geocoding operation.

Possible responses

Case of an address found (geocodeResponse/GeocodeResult/status is OK)

<ns2:geocodeResponse xmlns:ns2="http://geoconcept.com/gc/schemas">
        <GeocodeResult>
                <status>OK</status>
                <geocodedAddress>
                        <addressLine/>
                        <city>BAGNEUX</city>
                        <countryCode>FR</countryCode>
                        <postalCode>92220</postalCode>
                        <projection>epsg:4326</projection>
                        <srs>epsg:4326</srs>
                        <secondaryZone>920070110</secondaryZone>
                        <geocodeScore>20.0</geocodeScore>
                        <score>100.0</score>
                        <geocodeType>1</geocodeType>
                        <x>2.30811</x>
                        <y>48.79692</y>
                        <place>920070110</place>
                        <placeType>IRIS</placeType>
                        <streetNumber/>
                        <streetWayType/>
                        <streetWayName/>
                        <streetWay/>
                </geocodedAddress>
                <initialAddress>
                        <city>Bagneux</city>
                        <postalCode>92</postalCode>
                        <projection>epsg:4326</projection>
                </initialAddress>
        </GeocodeResult>
</ns2:geocodeResponse>

Case of an address that is not found (geocodeResponse/GeocodeResult/status is OK and no geocodedAddress)

<ns2:geocodeResponse xmlns:ns2="http://geoconcept.com/gc/schemas">
        <GeocodeResult>
                <status>OK</status>
                <initialAddress>
                        <city>#hdkvnjsdvn</city>
                </initialAddress>
        </GeocodeResult>
</ns2:geocodeResponse>

Case of a query containing 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>

Case of a query with a non-existant reprojection system ⇒ error with faultstring that contains the description

<soap:Fault>
        <faultcode xmlns:ns1="geoconcept.com">ns1:8</faultcode>
        <faultstring>Geocode failed Failed to process geocoding task Unsupported coordinate system 'epsg:432666666'</faultstring>
</soap:Fault>

FAQ

1. How is the score obtained in the score to be interpreted?
2. How many characters are returned in the tag postCode ?
3. What rules exist with regard to X-Y coordinates (format, coordinates range)?
4. Can this service be used to find and deliver a close-matching address?
5. How are Cedex entities handled?
6. Can you have all the components of an address as a single input item, in just one field?
7. Can you use several repositories at the same time?

1.	How is the score obtained in the score to be interpreted?
	A strict correspondance (equivalent to a score of 100) is equivalent to a no tolerance solution in effect, for a file that must not contain any errors at all. Choosing this score, you only accept suggestions of perfect matches between the reference table and the address sought. The higher the tolerance (in other words, the lower this score is set) the more the user accepts letters that are close matches between the addresses in the file to geocode and the reference table. The more likely it will be, also, that the software will assign false coordinates to certain addresses in the file due to a faulty interpretation. It is recommended that you only keep any candidates scoring 90 or higher. This score is a good compromise to the extent that one or two approximations between the addresses to geocode and the reference table are tolerated. It is strongly recommended that candidates with a score of less that 75 are NOT retained: this corresponds to at least 4 spelling or syntax mistakes in the address. Different criteria will have a bearing on the calculation of this score: the number of equivalent letters in the two strings; the number of words; the length of each word making up the string. In the case of correspondances between addresses, only the names of streets have a bearing on the search for a sppelling match. The type of street has an additional incidence on the score, but only in the case where the type of street sought and the one suggested are identical.
2.	How many characters are returned in the tag postCode ?
	Depends on the characteristics of postal codes for each country. Moreover, the returned string will be truncated to the first N characters if the address is not precise enough.
3.	What rules exist with regard to X-Y coordinates (format, coordinates range)?
	These are names in decimal format, with . as a separator of the decimal part. In the case where the geographic coordinates are in degrees, the return must be included within the range -180 and 180 (X=longitude) and -90 and 90 (Y=latitude), with 6 figures after the comma. In the case of projected coordinates, the result is in metres, with two figures after the comma.
4.	Can this service be used to find and deliver a close-matching address?
	If the town does not exist, it will return an empty list.
5.	How are Cedex entities handled?
	The grammar, described in the UGC.PDF documentation, applies a filter so as not to take Cedex and the codes that follow it into account during the search for addresses.
6.	Can you have all the components of an address as a single input item, in just one field?
	Yes, the addressline component can be used to perform a fulltext geocoding via a unique field containing the concatenation of all fields: street number, type of street, street name, post code and name of the town. The addresses input via the addressLine component are analysed in two phases: The mechanism for searching on word pattern will find, in the first instance, the town or towns present in the string. A search on the pattern then very quickly finds a label corresponding to a dictionary, in this case a dictionary of towns. This label can be badly spelt, with predictable or repeated errors in the user’s entering text at the keyboard when using Internet: duplicated latters, letters omitted, replacement of one letter with another given a similar sound to the resulting word (C instead of K, for example) part of a town name where the town name consists of several sub-entities. Following these lines of enquiry, a series of candidate towns is found in the shortest of timescales. Next, the pairs of towns found + the initial string without the "town" part that has just been recognised are given to the geocoder to perform the usual geocoding operation. Note: when the name of a town is also present in the name of a street, for example, "12 Rue d’Aix Antibes" there are potentially two candidates: Rue d’Aix à Antibes, and Rue d’Antibes à Aix. The best candidate is determined by its relative position in the string.
7.	Can you use several repositories at the same time?
	Yes, there are two methods: The first consists of deploying a configuration via the 'geocoding world' Cf. Administration / Tools / World Geocoding. The second, rather more technical, is deployed over a series of steps: Stop the Tomcat service, Put the referencial geocoding (8 files with .ugc.xxi extensions) in the appropriate directory. For example: Here, two tables are placed in the following directory: C:\[Home]\Geoconcept\UGC\JEE\ugc\reftables, in the framework of a default configuration. Edit the 'Service.xml' file associated to the JEE UGC module. The latter can be found here: C:\[Home]\Geoconcept\UGC\JEE\ugc\conf. In the text editor of your choice, copy/paste the text block framed by the <default-datasource> tags as many times as you have reference tables (in our example, there are 2 different sources, to copy/paste twice as a result), For each of the blocks copied/pasted, rename the <default-datasource> tag as <datasource>, The <file /> tag should indicate the name of one of the two reference tables. The <name /> tag allows you to give an alias to this source, for example here: "HERE".

Edition of the first block associated to the first reference table

  <datasource>
    <file>france_dom_M20.ugc.mdi</file>
    <name>HERE</name>
    <title />
    <abstract />
    <online-resource />
    <zone-meaning />
    <uniqueId-meaning />
    <secondaryZone-meaning />
    <roadId-meaning />
    <country />
    <version />
    <min-processors>0</min-processors>
    <max-processors>1</max-processors>
    <cache-enabled>true</cache-enabled>
    <cache-max-size>65536</cache-max-size>
    <city-scoring-method>levenshtein</city-scoring-method>
    <street-scoring-method>levenshtein</street-scoring-method>
    <min-streets>0</min-streets>
    <default-hierachy-search-depth>-1</default-hierachy-search-depth>
    <city-name-prefix-index-size>0</city-name-prefix-index-size>
    <strategy>
      <on-no-exact-city-match score-all-candidates="true" />
      <on-no-exact-street-match score-all-candidates="true" />
      <city-search-scoring max-error-threshold="85" />
      <street-search-scoring max-error-threshold="85" />
      <search hirerachy-depth="-1" />
      <!-- <force-search-two-keys /> -->
      <!-- <filter-zone filters="&gt;##" /> -->
    </strategy>
    <country />
    <coordinateSystem />
    <bounding-box />
    <max-candidates>10</max-candidates>
    <find-type>street number</find-type>
    <tolerate-find-type>7</tolerate-find-type>
    <max-meter-error>50</max-meter-error>
    <discrepancy>0.0</discrepancy>
    <discrepancy-along-street>0.0</discrepancy-along-street>
    <favor-city-match-element>favor city name</favor-city-match-element>
    <zone-match-digits>auto</zone-match-digits>
    <score-threshold>0.0</score-threshold>
    <score-threshold-to-tolerate-street-geocoding-type>0.0</score-threshold-to-tolerate-street-geocoding-type>
    <score-threshold-to-accept-city>0.88</score-threshold-to-accept-city>
  </datasource>

Leave the other parameters by default,
Repeat the steps for copying the <datasource> block, and setting up the <file/> and <name/> tags to configure the second data source.

Create the second block associated to the other reference table that will be exploited

  <datasource>
    <file>BD_ADRESSE_france_M20.ugc.mdi</file>
    <name>IGN</name>
    <title />
    <abstract />
    <online-resource />
    <zone-meaning />
    <uniqueId-meaning />
    <secondaryZone-meaning />
    <roadId-meaning />
    <country />
    <version />
    <min-processors>0</min-processors>
    <max-processors>1</max-processors>
    <cache-enabled>true</cache-enabled>
    <cache-max-size>65536</cache-max-size>
    <city-scoring-method>levenshtein</city-scoring-method>
    <street-scoring-method>levenshtein</street-scoring-method>
    <min-streets>0</min-streets>
    <default-hierachy-search-depth>-1</default-hierachy-search-depth>
    <city-name-prefix-index-size>0</city-name-prefix-index-size>
    <strategy>
      <on-no-exact-city-match score-all-candidates="true" />
      <on-no-exact-street-match score-all-candidates="true" />
      <city-search-scoring max-error-threshold="85" />
      <street-search-scoring max-error-threshold="85" />
      <search hirerachy-depth="-1" />
      <!-- <force-search-two-keys /> -->
      <!-- <filter-zone filters="&gt;##" /> -->
    </strategy>
    <country />
    <coordinateSystem />
    <bounding-box />
    <max-candidates>10</max-candidates>
    <find-type>street number</find-type>
    <tolerate-find-type>7</tolerate-find-type>
    <max-meter-error>50</max-meter-error>
    <discrepancy>0.0</discrepancy>
    <discrepancy-along-street>0.0</discrepancy-along-street>
    <favor-city-match-element>favor city name</favor-city-match-element>
    <zone-match-digits>auto</zone-match-digits>
    <score-threshold>0.0</score-threshold>
    <score-threshold-to-tolerate-street-geocoding-type>0.0</score-threshold-to-tolerate-street-geocoding-type>
    <score-threshold-to-accept-city>0.88</score-threshold-to-accept-city>
  </datasource>

Back-up the "XML Service" file and rerun the Tomcat service,
Connect to the Geoconcept Web portal and go into the Administration and then Parameters,
Add a new parameter key via the Add button, indicating the following information: Name = geocoder.countryDatasource and value = %country%, then validate by clicking on OK.
Now, when you call the Geocoding WebService, the user will have to call one of the two resources in their query, indicating in the <countrycode> parameter, the alias that has been defined beforehand, via the <name> tag. If no alias has been passed, the source defined in the geocoder.datasource parameter will be used by default.

Prev	Up	Next
	Home

Web Services documentation of Geoconcept Web - Web Services

Geocoding

Basic principles

Availability

Version change

V2

Parameters / properties

SOAP

REST

Possible responses

V1

Parameters / properties

SOAP

REST

Possible responses

FAQ