Reverse geocoding

Basic principles

The query includes a pair of coordinates as input, the service returns one or several possible responses (depending on the maximum number of responses desired), including the address, the post code, the town, the country, and the distance between the result and the start point (coordinates indicated as input).

This reverse geocoding service consults the road network installed previously in the dedicated directory associated to it.

Availability

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

Version change

Earlier versions of the web service have been conserved in Geoconcept Web to ensure compatibility with previous developments. We recommend using the most recent version.

Changes in relation to v3

The "coordinates" parameter has been added to the response

Changes in relation to v2

The "postalCode" parameter has been renamed "postCode"
The "distanceToLocation" parameter has been renamed "distanceMetersToLocation"
The "srs" parameter has been added to the response

V2

Parameters / properties

Input

parameter	description	optional	default
srs	projection (EPSG code such as epsg:4326 or wgs84)	yes
locations	Coordinates for the start point for reverse geocoding in SOAP, it will be necessary to supply coordinates in each of the dedicated tags <x></x> and <y></y> + in REST, the points are separated by the “;” character. The points are characterised by a pair of X, Y coordinates separated by a '.'.	no
graphName	indicate the name of the network or graph to use so the WebService can operate.	yes
maxDistance	maximum search distance to find neighbouring streets at the reverse geocoding start point if the parameter is passed, it is advisable to assign a value that is significantly higher than 1 (in metres).	no	1000
maxCandidates	maximum number of result addresses in the response if the parameter is passed, the minimum value to indicate is 1.	yes	1
maxDistanceBetweenCandidates	Maximum distance (in metres) between each candidate. if the parameter is passed, it is advisable to assign a value that is significantly higher than 1 (in metres).	no	100

Output

Reminder for the coordinates of the start point of the search(reverseGeocodingV2Response)

property	type	min/max	description
location	string	0/1	X,Y coordinates for the start point for the reverse geocoding
srs	string	0/1	projection (EPSG code such as epsg:4326 or wgs84)
address/addresses		0/unlimited	list of (candidate) addresses returned

Candidates returned (Address)

property	type	min/max	description
addressLine	string	0/1	street found
postCode	string	0/1	post code found
city	string	0/1	town associated with the candidate returned
country	string	0/1	country associated to the candidate returned
distanceMetersToLocation	double	1/1	Distance (in metres) between the candidate returned and the start point
coordinates	string	1/1	Address coordinates

SOAP

WSDL

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

Query

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sch="http://geoconcept.com/gc/schemas">
   <soapenv:Header/>
   <soapenv:Body>
      <sch:reverseGeocodingV3>
         <!--Optional:-->
         <request>
            <!--Optional:-->
            <srs>epsg:4326</srs>
            <!--Zero or more repetitions:-->
            <locations>
               <x>-1.565769</x>
               <y>47.226236</y>
            </locations>
            <!--Optional:-->
            <graphName></graphName>
            <!--Optional:-->
            <maxDistance>1000</maxDistance>
            <!--Optional:-->
            <maxCandidates>2</maxCandidates>
            <!--Optional:-->
            <maxDistanceBetweenCandidates>100</maxDistanceBetweenCandidates>
         </request>
      </sch:reverseGeocodingV2>
   </soapenv:Body>
</soapenv:Envelope>

Response

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:reverseGeocodingV3Response xmlns:ns2="http://geoconcept.com/gc/schemas">
        <reverseGeocodingResultsV3>
           <status>OK</status>
           <reverseGeocodingResult>
              <location>-1.565769;47.226236</location>
              <srs>epsg:4326</srs>
              <addresses>
                 <address>
                    <addressLine>26 RUE DU MAINE</addressLine>
                    <postCode>44000</postCode>
                    <city>NANTES</city>
                    <country>France</country>
                    <distanceMetersToLocation>1.2300580212448586</distanceMetersToLocation>
                    <coordinates>-1.565757,47.226229</coordinates>
                 </address>
                 <address>
                    <addressLine>2 RUE JOYAU</addressLine>
                    <postCode>44000</postCode>
                    <city>NANTES</city>
                    <country>France</country>
                    <distanceMetersToLocation>27.310568595900534</distanceMetersToLocation>
                    <coordinates>-1.566068,47.226099</coordinates>
                 </address>
              </addresses>
           </reverseGeocodingResult>
        </reverseGeocodingResultsV3>
      </ns2:reverseGeocodingV2Response>
   </soap:Body>
</soap:Envelope>

REST

Query

JSON query

http://<server>/<webapp>/api/lbs/reverseGeocoding/v3.json?locations=-1.565769,47.226236&maxDistance=1000&maxCandidates=2&maxDistanceBetweenCandidates=100

JSON-P query

http://<server>/<webapp>/api/lbs/reverseGeocoding/v3.json?locations=-1.565769,47.226236&maxDistance=1000&maxCandidates=2&maxDistanceBetweenCandidates=100&fonction=myFonction

XML query

http://<server>/<webapp>/api/lbs/reverseGeocoding/v3.xml?locations=-1.565769,47.226236&maxDistance=1000&maxCandidates=2&maxDistanceBetweenCandidates=100

Response

The response is always in UTF-8 format.

JSON format

{
   "message": null,
   "status": "OK",
   "reverseGeocodingResults": [
      {
         "location": "-1.565769;47.226236",
         "srs": null,
         "addresses": [
            {
               "addressLine": "26 RUE DU MAINE",
               "postCode": "44000",
               "city": "NANTES",
               "country": "France",
               "distanceMetersToLocation": 1.2300581,
               "coordinates": "-1.565757,47.226229"
            },
            {
               "addressLine": "2 RUE JOYAU",
               "postCode": "44000",
               "city": "NANTES",
               "country": "France",
               "distanceMetersToLocation": 27.310568,
               "coordinates": "-1.566068,47.226099"
            }
         ]
      }
   ]
}

JSON-P format

myCallback(
    {
       "message": null,
       "status": "OK",
       "reverseGeocodingResults": [
          {
             "location": "-1.565769;47.226236",
             "srs": null,
             "addresses": [
                {
                   "addressLine": "26 RUE DU MAINE",
                   "postCode": "44000",
                   "city": "NANTES",
                   "country": "France",
                   "distanceMetersToLocation": 1.2300581,
                   "coordinates": "-1.565757,47.226229"
                },
                {
                   "addressLine": "2 RUE JOYAU",
                   "postCode": "44000",
                   "city": "NANTES",
                   "country": "France",
                   "distanceMetersToLocation": 27.310568,
                   "coordinates": "-1.566068,47.226099"
                }
             ]
          }
       ]
    }
)

XML format

<reverseGeocodingResultsV3>
   <status>OK</status>
   <reverseGeocodingResult>
      <location>-1.565769;47.226236</location>
      <addresses>
         <address>
            <addressLine>26 RUE DU MAINE</addressLine>
            <postCode>44000</postCode>
            <city>NANTES</city>
            <country>France</country>
            <distanceMetersToLocation>1.2300580212448586</distanceMetersToLocation>
            <coordinates>-1.565757,47.226229</coordinates>
         </address>
         <address>
            <addressLine>2 RUE JOYAU</addressLine>
            <postCode>44000</postCode>
            <city>NANTES</city>
            <country>France</country>
            <distanceMetersToLocation>27.310568595900534</distanceMetersToLocation>
            <coordinates>-1.566068,47.226099</coordinates>
         </address>
      </addresses>
   </reverseGeocodingResult>
</reverseGeocodingResultsV3>

Possible responses

Example of a correct reverse geocoding (reverseGeocodingResult/status is OK)

<reverseGeocodingResultsV3>
   <status>OK</status>
   <reverseGeocodingResult>
      <location>-1.565769;47.226236</location>
      <addresses>
         <address>
            <addressLine>26 RUE DU MAINE</addressLine>
            <postCode>44000</postCode>
            <city>NANTES</city>
            <country>France</country>
            <distanceMetersToLocation>1.2300580212448586</distanceMetersToLocation>
            <coordinates>-1.565757,47.226229</coordinates>
         </address>
         <address>
            <addressLine>2 RUE JOYAU</addressLine>
            <postCode>44000</postCode>
            <city>NANTES</city>
            <country>France</country>
            <distanceMetersToLocation>27.310568595900534</distanceMetersToLocation>
            <coordinates>-1.566068,47.226099</coordinates>
         </address>
      </addresses>
   </reverseGeocodingResult>
</reverseGeocodingResultsV3>

Case of a reverse geocoding operation where the maxDistance does not respect a value of > 1 (a minimum value of 100 is recommended). (reverseGeocodingResult/status is OK)

<?xml version="1.0" encoding="UTF-8"?>
<serviceResult>
   <message>ServiceException: Error in reverse geocoding computation Error in smartrouting Failed to execute ReverseGeocode com.geoconcept.smartrouting.SmartRoutingNativeException: failed to connect { -1.565769, 47.226236, 0.000000 } failed to connect { -1.565769, 47.226236, 0.000000 }</message>
   <status>ERROR</status>
</serviceResult>

In the case of a query where one of the parameters (<locations>,…) is not set. (reverseGeocodingResult/status is ERROR)

<reverseGeocodingResultsV3>
    <message>locations must be not null</message>
    <status>ERROR</status>
</reverseGeocodingResultsV3>

Case of a query that does not snap to the graph (reverseGeocodingResult/status is ERROR)

<serviceResult>
    <message>ServiceException: Error in reverse geocoding computation Error in smartrouting Failed to execute ReverseGeocode com.geoconcept.smartrouting.SmartRoutingNativeException: failed to connect { -1.565769, 147.226236, 0.000000 } failed to connect { -1.565769, 147.226236, 0.000000 }
    </message>
    <status>ERROR</status>
</serviceResult>

V2

Parameters / properties

Input

parameter	description	optional	default
srs	projection (EPSG code such as epsg:4326 or wgs84)	yes
locations	Coordinates for the start point for reverse geocoding in SOAP, it will be necessary to supply coordinates in each of the dedicated tags <x></x> and <y></y> + in REST, the points are separated by the “;” character. The points are characterised by a pair of X, Y coordinates separated by a '.'.	no
graphName	indicate the name of the network or graph to use so the WebService can operate.	yes
maxDistance	maximum search distance to find neighbouring streets at the reverse geocoding start point if the parameter is passed, it is advisable to assign a value that is significantly higher than 1 (in metres).	no	1000
maxCandidates	maximum number of result addresses in the response if the parameter is passed, the minimum value to indicate is 1.	yes	1
maxDistanceBetweenCandidates	Maximum distance (in metres) between each candidate. if the parameter is passed, it is advisable to assign a value that is significantly higher than 1 (in metres).	no	100

Output

Reminder for the coordinates of the start point of the search(reverseGeocodingV2Response)

property	type	min/max	description
location	string	0/1	X,Y coordinates for the start point for the reverse geocoding
srs	string	0/1	projection (EPSG code such as epsg:4326 or wgs84)
address/addresses		0/unlimited	list of (candidate) addresses returned

Candidates returned (Address)

property	type	min/max	description
addressLine	string	0/1	street found
postCode	string	0/1	post code found
city	string	0/1	town associated with the candidate returned
country	string	0/1	country associated to the candidate returned
distanceMetersToLocation	double	1/1	Distance (in metres) between the candidate returned and the start point

SOAP

WSDL

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

Query

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sch="http://geoconcept.com/gc/schemas">
   <soapenv:Header/>
   <soapenv:Body>
      <sch:reverseGeocodingV2>
         <!--Optional:-->
         <request>
            <!--Optional:-->
            <srs>epsg:4326</srs>
            <!--Zero or more repetitions:-->
            <locations>
               <x>-1.565769</x>
               <y>47.226236</y>
            </locations>
            <!--Optional:-->
            <graphName></graphName>
            <!--Optional:-->
            <maxDistance>1000</maxDistance>
            <!--Optional:-->
            <maxCandidates>2</maxCandidates>
            <!--Optional:-->
            <maxDistanceBetweenCandidates>100</maxDistanceBetweenCandidates>
         </request>
      </sch:reverseGeocodingV2>
   </soapenv:Body>
</soapenv:Envelope>

Response

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:reverseGeocodingV2Response xmlns:ns2="http://geoconcept.com/gc/schemas">
         <ReverseGeocodingResults>
            <status>OK</status>
            <reverseGeocodingResult>
               <location>-1,565769;47,226236</location>
               <srs>epsg:4326</srs>
               <addresses>
                  <address>
                     <addressLine>24 RUE DU MAINE</addressLine>
                     <postCode>44000</postCode>
                     <city>NANTES</city>
                     <country>France</country>
                     <distanceMetersToLocation>1.2509365114145279</distanceMetersToLocation>
                  </address>
                  <address>
                     <addressLine>2 RUE JOYAU</addressLine>
                     <postCode>44000</postCode>
                     <city>NANTES</city>
                     <country>France</country>
                     <distanceMetersToLocation>27.312077690953934</distanceMetersToLocation>
                  </address>
               </addresses>
            </reverseGeocodingResult>
         </ReverseGeocodingResults>
      </ns2:reverseGeocodingV2Response>
   </soap:Body>
</soap:Envelope>

REST

Query

JSON query

http://<server>/<webapp>/api/lbs/reverseGeocoding/v2.json?locations=-1.565769,47.226236&maxDistance=1000&maxCandidates=2&maxDistanceBetweenCandidates=100

JSON-P query

http://<server>/<webapp>/api/lbs/reverseGeocoding/v2.json?locations=-1.565769,47.226236&maxDistance=1000&maxCandidates=2&maxDistanceBetweenCandidates=100&fonction=myFonction

XML query

http://<server>/<webapp>/api/lbs/reverseGeocoding/v2.xml?locations=-1.565769,47.226236&maxDistance=1000&maxCandidates=2&maxDistanceBetweenCandidates=100

Response

The response is always in UTF-8 format.

JSON format

{
  "message": null,
  "status": "OK",
  "reverseGeocodingResults": [
    {
      "location": "-1.565769;47.226236",
      "addresses": [
        {
          "addressLine": "26 RUE DU MAINE",
          "postalCode": "44000",
          "city": "NANTES",
          "country": "France",
          "distanceToLocation": 1.2370980024960025
        },
        {
          "addressLine": "2 RUE JOYAU",
          "postalCode": "44000",
          "city": "NANTES",
          "country": "France",
          "distanceToLocation": 27.302664051548852
        }
      ]
    }
  ]
}

JSON-P format

myCallback(
    {
      "message": null,
      "status": "OK",
      "reverseGeocodingResults": [
        {
          "location": "-1.565769;47.226236",
          "addresses": [
            {
              "addressLine": "26 RUE DU MAINE",
              "postalCode": "44000",
              "city": "NANTES",
              "country": "France",
              "distanceToLocation": 1.2370980024960025
            },
            {
              "addressLine": "2 RUE JOYAU",
              "postalCode": "44000",
              "city": "NANTES",
              "country": "France",
              "distanceToLocation": 27.302664051548852
            }
          ]
        }
      ]
    }
)

XML format

<reverseGeocodingResultsV2>
   <status>OK</status>
   <reverseGeocodingResult>
      <location>-1.565769;47.226236</location>
      <srs>epsg:4326</srs>
      <addresses>
         <address>
            <addressLine>26 RUE DU MAINE</addressLine>
            <postCode>44000</postCode>
            <city>NANTES</city>
            <country>France</country>
            <distanceMetersToLocation>1.2370980024960025</distanceMetersToLocation>
         </address>
         <address>
            <addressLine>2 RUE JOYAU</addressLine>
            <postCode>44000</postCode>
            <city>NANTES</city>
            <country>France</country>
            <distanceMetersToLocation>27.302664051548852</distanceMetersToLocation>
         </address>
      </addresses>
   </reverseGeocodingResult>
</reverseGeocodingResultsV2>

Possible responses

Example of a correct reverse geocoding (reverseGeocodingResult/status is OK)

<reverseGeocodingResultsV2>
   <status>OK</status>
   <reverseGeocodingResult>
      <location>-1.565769;47.226236</location>
      <srs>epsg:4326</srs>
      <addresses>
         <address>
            <addressLine>26 RUE DU MAINE</addressLine>
            <postCode>44000</postCode>
            <city>NANTES</city>
            <country>France</country>
            <distanceMetersToLocation>1.2370980024960025</distanceMetersToLocation>
         </address>
         <address>
            <addressLine>2 RUE JOYAU</addressLine>
            <postCode>44000</postCode>
            <city>NANTES</city>
            <country>France</country>
            <distanceMetersToLocation>27.302664051548852</distanceMetersToLocation>
         </address>
      </addresses>
   </reverseGeocodingResult>
</reverseGeocodingResultsV2>

Case of a reverse geocoding operation where the maxDistance does not respect a value of > 1 (a minimum value of 100 is recommended). (reverseGeocodingResult/status is OK)

<?xml version="1.0" encoding="UTF-8"?>
<serviceResult>
   <message>ServiceException: Error in reverse geocoding computation Error in smartrouting Failed to execute ReverseGeocode com.geoconcept.smartrouting.SmartRoutingNativeException: failed to connect { -1.565769, 47.226236, 0.000000 } failed to connect { -1.565769, 47.226236, 0.000000 }</message>
   <status>ERROR</status>
</serviceResult>

In the case of a query where one of the parameters (<locations>,…) is not set. (reverseGeocodingResult/status is ERROR)

<reverseGeocodingResultsV2>
    <message>locations must be not null</message>
    <status>ERROR</status>
</reverseGeocodingResultsV2>

Case of a query that does not snap to the graph from version 2.0.9 of SmartRouting Server (reverseGeocodingResult/status is ERROR)

<serviceResult>
    <message>ServiceException: Error in reverse geocoding computation Error in smartrouting Failed to execute ReverseGeocode com.geoconcept.smartrouting.SmartRoutingNativeException: failed to connect { -1.565769, 147.226236, 0.000000 } failed to connect { -1.565769, 147.226236, 0.000000 }
    </message>
    <status>ERROR</status>
</serviceResult>

V1

Parameters / properties

Input

parameter	description	optional
srs	projection (EPSG code such as epsg:4326 or wgs84)	yes
locations	Coordinates for the start point for reverse geocoding in SOAP, it will be necessary to supply coordinates in each of the dedicated tags <x></x> and <y></y> + in REST, the points are separated by the “;” character. The points are characterised by a pair of X, Y coordinates separated by a '.'.	no
graphName	indicate the name of the network or graph to use so the WebService can operate.	yes
maxDistance	maximum search distance to find neighbouring streets at the reverse geocoding start point if the parameter is passed, it is advisable to assign a value that is significantly higher than 1 (in metres).	no
maxCandidates	maximum number of result addresses in the response if the parameter is passed, the minimum value to indicate is 1.	yes
maxDistanceBetweenCandidates	Maximum distance (in metres) between each candidate. if the parameter is passed, it is advisable to assign a value that is significantly higher than 1 (in metres).	no

Output

Reminder for the coordinates of the start point of the search (location)

property	type	min/max	description
location	string	0/1	X,Y coordinates for the start point for the reverse geocoding
address/addresses		0/unlimited	list of (candidate) addresses returned

Candidates returned (Address)

property	type	min/max	description
addressLine	string	0/1	street found
postalCode	string	0/1	post code found
city	string	0/1	town associated with the candidate returned
country	string	0/1	country associated to the candidate returned
distanceToLocation	integer	1/1	Distance (in metres) between the candidate returned and the start point

SOAP

WSDL

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

Query

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sch="http://geoconcept.com/gc/schemas">
   <soapenv:Header/>
   <soapenv:Body>
      <sch:reverseGeocoding>
         <!--Optional:-->
         <request>
            <!--Optional:-->
            <srs></srs>
            <!--Zero or more repetitions:-->
            <locations>
               <x>2.324382</x>
               <y>48.803305</y>
            </locations>
            <!--Optional:-->
            <graphName></graphName>
            <!--Optional:-->
            <maxDistance>1000</maxDistance>
            <!--Optional:-->
            <maxCandidates>10</maxCandidates>
            <!--Optional:-->
            <maxDistanceBetweenCandidates>100</maxDistanceBetweenCandidates>
         </request>
      </sch:reverseGeocoding>
   </soapenv:Body>
</soapenv:Envelope>

Response

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:reverseGeocodingResponse xmlns:ns2="http://geoconcept.com/gc/schemas">
         <ReverseGeocodingResults>
            <status>OK</status>
            <reverseGeocodingResult>
               <location>2.324382;48.803305</location>
               <addresses>
                  <address>
                     <addressLine>AVENUE ARISTIDE BRIAND</addressLine>
                     <postalCode>92220</postalCode>
                     <city>BAGNEUX</city>
                     <country>FRANCE</country>
                     <distanceToLocation>18.661267300047538</distanceToLocation>
                  </address>
                  <address>
                     <addressLine>RUE DU MIDI</addressLine>
                     <postalCode>94110</postalCode>
                     <city>ARCUEIL</city>
                     <country>FRANCE</country>
                     <distanceToLocation>29.691380904228758</distanceToLocation>
                  </address>
               </addresses>
            </reverseGeocodingResult>
         </ReverseGeocodingResults>
      </ns2:reverseGeocodingResponse>
   </soap:Body>
</soap:Envelope>

REST

Query

JSON query

http://<server>/<webapp>/api/lbs/reverseGeocoding.json?locations=2.324382,48.803305&maxDistance=1000&maxCandidates=2&maxDistanceBetweenCandidates=100

JSON-P query

http://<server>/<webapp>/api/lbs/reverseGeocoding.json?locations=2.324382,48.803305&maxDistance=1000&maxCandidates=2&maxDistanceBetweenCandidates=100&fonction=myFonction

XML query

http://<server>/<webapp>/api/lbs/reverseGeocoding.xml?locations=2.324382,48.803305&maxDistance=1000&maxCandidates=2&maxDistanceBetweenCandidates=100

Response

The response is always in UTF-8 format.

JSON format

{
   "message": null,
   "status": "OK",
   "reverseGeocodingResults": [   {
      "location": "2.324382;48.803305",
      "addresses":       [
                  {
            "addressLine": "AVENUE ARISTIDE BRIAND",
            "postalCode": "92220",
            "city": "BAGNEUX",
            "country": "FRANCE",
            "distanceToLocation": 18.661267300047538
         },
                  {
            "addressLine": "RUE DU MIDI",
            "postalCode": "94110",
            "city": "ARCUEIL",
            "country": "FRANCE",
            "distanceToLocation": 29.691380904228758
         }
      ]
   }]
}

JSON-P format

myCallback({
        "message":null,"status":"OK",
        "reverseGeocodingResults":[
                {
                        "location":"2.324382;48.803305",
                                "addresses":[
                                        {
                                                "addressLine":"AVENUE ARISTIDE BRIAND",
                                                "postalCode":"92220",
                                                "city":"BAGNEUX",
                                                "country":"FRANCE",
                                                "distanceToLocation":18.661267300047538
                                        },
                                        {
                                                "addressLine":"RUE DU MIDI",
                                                "postalCode":"94110",
                                                "city":"ARCUEIL",
                                                "country":"FRANCE",
                                                "distanceToLocation":29.691380904228758
                                        }
]}]}

XML format

<reverseGeocodingResults>
   <status>OK</status>
   <reverseGeocodingResult>
      <location>2.324382;48.803305</location>
      <addresses>
         <address>
            <addressLine>AVENUE ARISTIDE BRIAND</addressLine>
            <postalCode>92220</postalCode>
            <city>BAGNEUX</city>
            <country>FRANCE</country>
            <distanceToLocation>18.661267300047538</distanceToLocation>
         </address>
         <address>
            <addressLine>RUE DU MIDI</addressLine>
            <postalCode>94110</postalCode>
            <city>ARCUEIL</city>
            <country>FRANCE</country>
            <distanceToLocation>29.691380904228758</distanceToLocation>
         </address>
      </addresses>
   </reverseGeocodingResult>
</reverseGeocodingResults>

Possible responses

Example of a correct reverse geocoding (reverseGeocodingResult/status is OK)

<reverseGeocodingResults>
   <status>OK</status>
   <reverseGeocodingResult>
      <location>2.324382;48.803305</location>
      <addresses>
         <address>
            <addressLine>AVENUE ARISTIDE BRIAND</addressLine>
            <postalCode>92220</postalCode>
            <city>BAGNEUX</city>
            <country>FRANCE</country>
            <distanceToLocation>18.661267300047538</distanceToLocation>
         </address>
         <address>
            <addressLine>RUE DU MIDI</addressLine>
            <postalCode>94110</postalCode>
            <city>ARCUEIL</city>
            <country>FRANCE</country>
            <distanceToLocation>29.691380904228758</distanceToLocation>
         </address>
      </addresses>
   </reverseGeocodingResult>
</reverseGeocodingResults>

Case of a reverse geocoding operation where the maxDistanceBetweenCandidates does not respect a value of > 1 (a minimum value of 100 is recommended). (reverseGeocodingResult/status is OK)

<reverseGeocodingResults>
   <status>OK</status>
   <reverseGeocodingResult>
      <location>2.324382;48.803305</location>
      <addresses>
         <address>
            <addressLine>AVENUE ARISTIDE BRIAND</addressLine>
            <postalCode>92220</postalCode>
            <city>BAGNEUX</city>
            <country>FRANCE</country>
            <distanceToLocation>18.661267300047538</distanceToLocation>
         </address>
      </addresses>
   </reverseGeocodingResult>
</reverseGeocodingResults>

Case of a reverse geocoding operation where the maxDistance does not respect a value of > 1 (a minimum value of 100 is recommended). (reverseGeocodingResult/status is OK)

<reverseGeocodingResults>
   <status>OK</status>
   <reverseGeocodingResult>
      <location>2.324382;48.803305</location>
      <addresses/>
   </reverseGeocodingResult>
</reverseGeocodingResults>

Case of a query where the <location> parameter is not indicated. (reverseGeocodingResult/status is ERROR)

<reverseGeocodingResults>
   <message>locations must be not null</message>
   <status>ERROR</status>
</reverseGeocodingResults>

Case of a query that does not snap to the graph from version 2.0.9 of SmartRouting Server (serviceResult/status is ERROR)

<serviceResult>
    <message>ServiceException: Error in reverse geocoding computation
    Error in smartrouting
    Failed to execute ReverseGeocode
com.geoconcept.smartrouting.SmartRoutingNativeException: failed to connect { 2.165931, 49.218690, 0.000000 }
failed to connect { 2.165931, 49.218690, 0.000000 }
    </message>
    <status>ERROR</status>
</serviceResult>

FAQ

1. How is the maximum distance interpreted?
2. What is the role of the maxCandidates parameter?
3. What is the significance of the maxDistanceBetweenCandidates parameter?
4. Can I use aliases instead of .siti file names to call a datasource?

1.	How is the maximum distance interpreted?
	The <maxDistance> tag is mandatory and must have a value higher than 1. Take care, nonetheless, if the maximum distance is not high enough, as the risk would be not to have any candidate returned at all.
2.	What is the role of the maxCandidates parameter?
	This parameter allows you to define the number of responses you want to obtain, in the event that there are a large number of potential candidates. If no value is indicated, it is the iti.maxTargets value assigned in the Geoconcept Web Administration that is taken.
3.	What is the significance of the maxDistanceBetweenCandidates parameter?
	If this parameter is filled in incorrectly, the webservice cannot return a positive response. We strongly advise assigning a value of > 1. If no value is mentioned, it is the iti.candidatesDeltaDistance value assigned in the Geoconcept Web Administration that will predominate. Care is needed, as if the distance between the candidates is not large enough, there is a significant risk of not having any candidates returned at all.
4.	Can I use aliases instead of .siti file names to call a datasource?
	Yes. A specific configuration has to be performed to enable exploitation of the alias enabling utilisation of several sources for graphs. The steps to respect are the following: Stop the Tomcat service, Store the graphs (.siti and as an option the .siti.MG and .siti.GA files) in the appropriate directory. For example: here two graphs are stored in the following directory: [Home]\Geoconcept\SmartRouting\server\SRJEE\smartrouting\graphs, in the framework of a default parameter. Edit the 'Service.xml' file associated to the JEE SmartRouting module. This can be found here [Home]\Geoconcept\SmartRouting\server\SRJEE\smartrouting\conf. In the text editor of your choice, copy/paste as many times as you have graphs, the text block framed by the <datasource> tags shown below (in our example, there are 2 different sources, to be copied/pasted twice as a result), Copy this <datasource> block under the <default-datasource> tag of the initial block, The <file /> tag should indicate the name of one of the two graphs. The tag allows you to give an alias to this source, for example here: «HEREQ414».

Editing the first block associated to the first graph

        <datasource>
        <file>navteq_maps_for_geoconcept_Q414_france_v1.siti</file>
        <name>HEREQ414</name>

        <load-graph-settings>
            <full-load>false</full-load>
            <primary-language>en</primary-language>
        </load-graph-settings>

        <calculate-route-options>
            <vehicle-type/>
            <!-- a vehicle type name present in the vehicle types catalog -->
            <vehicle-type-id/>
            <!-- a vehicle type identifier present in the vehicle types catalog -->
            <route-search-criteria>time</route-search-criteria>
            <!-- distance, time, or an integer matching cost table index (graph dependant) -->
            <max-graph-snap-distance>500</max-graph-snap-distance>
            <!-- in meters -->
            <graph-snap-speed>1.11111111</graph-snap-speed>
            <!-- in m/s -->
            <route-descr-items/>
            <!-- composition (separated by comma) -->
            <reference-level>4</reference-level>
            <reject-flags/>
            <!-- composition (separated by comma) -->
            <speed-profile/>
            <input-coordinate-system/>
            <output-coordinate-system/>
            <use-meta-graph>true</use-meta-graph>
            <use-graph-accelerator>true</use-graph-accelerator>
            <fields/>
            <!-- composition (separated by comma) -->
            <tour-optimization>auto</tour-optimization>
            <language/>
            <!-- default output language -->
        </calculate-route-options>

        <calculate-route-settings>
            <calculate-ecotax>true</calculate-ecotax>
            <!-- calculate ecotax when available  -->
        </calculate-route-settings>

        <!-- if a section named 'search-around-options' (same definition as calculate-route-options) is present it defines particular default options for search around -->
        <!-- if a section named 'calculate-route-matrix-options' (same definition as calculate-route-options) is present it defines particular default options for calculate route matrix -->
        <!-- if a section named 'calculate-tour-options' (same definition as calculate-route-options) is present it defines particular default options for calculate tour -->

        <!-- if a section named 'calculate-route-matrix-settings' (same definition as calculate-route-matrix-settings) is present it defines particular settings for calculate route matrix -->
        <!-- if a section named 'search-around-settings' (same definition as calculate-route-settings) is present it defines particular settings for search around -->

        <reverse-geocode-options>

            <max-distance>1000</max-distance>
            <!-- in meters -->
            <max-distance-between-candidates>2</max-distance-between-candidates>
            <!-- in meters -->
            <max-candidates>10</max-candidates>

            <input-coordinate-system/>
            <output-coordinate-system/>

            <include-street-number>true</include-street-number>
            <accept-emtpy-segments>true</accept-emtpy-segments>

            <language/>
            <places/>

        </reverse-geocode-options>

        <!-- reverse geocoding configuration usually depends on each particular graph -->
        <reverse-geocode-settings>
            <address-line-field>${built-in-field:name}</address-line-field>
            <city-name-field>City name</city-name-field>

            <postal-code-field>Postcode</postal-code-field>

            <country-field>Country</country-field>

            <right-suffix> right</right-suffix>
            <left-suffix> left</left-suffix>

            <number-begin-left-field>Begin left number</number-begin-left-field>
            <number-end-left-field>End left number</number-end-left-field>
            <number-begin-right-field>Begin right number</number-begin-right-field>
            <number-end-right-field>End right number</number-end-right-field>

        </reverse-geocode-settings>

        <calculate-tour-settings>
            <tour-optimization-auto-threshold>10</tour-optimization-auto-threshold>
        </calculate-tour-settings>

        <calculate-concentric-reachable-areas-options>
            <vehicle-type/>
            <!-- a vehicle type name present in the vehicle types catalog -->
            <vehicle-type-id/>
            <!-- a vehicle type identifier present in the vehicle types catalog -->
            <route-search-criteria>time</route-search-criteria>
            <!-- distance, time, or an integer matching cost table index (graph dependant) -->
            <max-graph-snap-distance>500</max-graph-snap-distance>
            <!-- in meters -->
            <graph-snap-speed>1.11111111</graph-snap-speed>
            <!-- in m/s -->
            <route-descr-items/>
            <!-- composition (separated by comma) -->
            <reference-level>4</reference-level>
            <reject-flags/>
            <!-- composition (separated by comma) -->
            <speed-profile/>
            <input-coordinate-system/>
            <output-coordinate-system/>
            <use-meta-graph>true</use-meta-graph>
            <use-graph-accelerator>true</use-graph-accelerator>

            <default-reachable-area-specification>
                <row-col>2000</row-col>
                <tile-resolution>50</tile-resolution>
                <max-holes>0</max-holes>
                <min-hole-size>0</min-hole-size>
                <extended-smoothing>false</extended-smoothing>
                <accept-non-connectable-links>true</accept-non-connectable-links>
            </default-reachable-area-specification>

        </calculate-concentric-reachable-areas-options>

        <calculate-concentric-reachable-areas-settings>
        </calculate-concentric-reachable-areas-settings>
    </datasource>

leave the other default parameters, except where you decide to create a configuration that is specific to your installation.
Repeat the steps of copying the <datasource> block and the editing of the <file/> and <name/> tags to configure the second data source.

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

        <datasource>
        <file>BD_ADRESSE_France_v4.siti</file>
        <name>IGN</name>

        <load-graph-settings>
            <full-load>false</full-load>
            <primary-language>en</primary-language>
        </load-graph-settings>

        <calculate-route-options>
            <vehicle-type/>
            <!-- a vehicle type name present in the vehicle types catalog -->
            <vehicle-type-id/>
            <!-- a vehicle type identifier present in the vehicle types catalog -->
            <route-search-criteria>time</route-search-criteria>
            <!-- distance, time, or an integer matching cost table index (graph dependant) -->
            <max-graph-snap-distance>500</max-graph-snap-distance>
            <!-- in meters -->
            <graph-snap-speed>1.11111111</graph-snap-speed>
            <!-- in m/s -->
            <route-descr-items/>
            <!-- composition (separated by comma) -->
            <reference-level>4</reference-level>
            <reject-flags/>
            <!-- composition (separated by comma) -->
            <speed-profile/>
            <input-coordinate-system/>
            <output-coordinate-system/>
            <use-meta-graph>true</use-meta-graph>
            <use-graph-accelerator>true</use-graph-accelerator>
            <fields/>
            <!-- composition (separated by comma) -->
            <tour-optimization>auto</tour-optimization>
            <language/>
            <!-- default output language -->
        </calculate-route-options>

        <calculate-route-settings>
            <calculate-ecotax>true</calculate-ecotax>
            <!-- calculate ecotax when available  -->
        </calculate-route-settings>

        <!-- if a section named 'search-around-options' (same definition as calculate-route-options) is present it defines particular default options for search around -->
        <!-- if a section named 'calculate-route-matrix-options' (same definition as calculate-route-options) is present it defines particular default options for calculate route matrix -->
        <!-- if a section named 'calculate-tour-options' (same definition as calculate-route-options) is present it defines particular default options for calculate tour -->

        <!-- if a section named 'calculate-route-matrix-settings' (same definition as calculate-route-matrix-settings) is present it defines particular settings for calculate route matrix -->
        <!-- if a section named 'search-around-settings' (same definition as calculate-route-settings) is present it defines particular settings for search around -->

        <reverse-geocode-options>

            <max-distance>1000</max-distance>
            <!-- in meters -->
            <max-distance-between-candidates>2</max-distance-between-candidates>
            <!-- in meters -->
            <max-candidates>10</max-candidates>

            <input-coordinate-system/>
            <output-coordinate-system/>

            <include-street-number>true</include-street-number>
            <accept-emtpy-segments>true</accept-emtpy-segments>

            <language/>
            <places/>

        </reverse-geocode-options>

        <!-- reverse geocoding configuration usually depends on each particular graph -->
        <reverse-geocode-settings>
            <address-line-field>${built-in-field:name}</address-line-field>
            <city-name-field>City name</city-name-field>

            <postal-code-field>Postcode</postal-code-field>

            <country-field>Country</country-field>

            <right-suffix> right</right-suffix>
            <left-suffix> left</left-suffix>

            <number-begin-left-field>Begin left number</number-begin-left-field>
            <number-end-left-field>End left number</number-end-left-field>
            <number-begin-right-field>Begin right number</number-begin-right-field>
            <number-end-right-field>End right number</number-end-right-field>

        </reverse-geocode-settings>

        <calculate-tour-settings>
            <tour-optimization-auto-threshold>10</tour-optimization-auto-threshold>
        </calculate-tour-settings>

        <calculate-concentric-reachable-areas-options>
            <vehicle-type/>
            <!-- a vehicle type name present in the vehicle types catalog -->
            <vehicle-type-id/>
            <!-- a vehicle type identifier present in the vehicle types catalog -->
            <route-search-criteria>time</route-search-criteria>
            <!-- distance, time, or an integer matching cost table index (graph dependant) -->
            <max-graph-snap-distance>500</max-graph-snap-distance>
            <!-- in meters -->
            <graph-snap-speed>1.11111111</graph-snap-speed>
            <!-- in m/s -->
            <route-descr-items/>
            <!-- composition (separated by comma) -->
            <reference-level>4</reference-level>
            <reject-flags/>
            <!-- composition (separated by comma) -->
            <speed-profile/>
            <input-coordinate-system/>
            <output-coordinate-system/>
            <use-meta-graph>true</use-meta-graph>
            <use-graph-accelerator>true</use-graph-accelerator>

            <default-reachable-area-specification>
                <row-col>2000</row-col>
                <tile-resolution>50</tile-resolution>
                <max-holes>0</max-holes>
                <min-hole-size>0</min-hole-size>
                <extended-smoothing>false</extended-smoothing>
                <accept-non-connectable-links>true</accept-non-connectable-links>
            </default-reachable-area-specification>

        </calculate-concentric-reachable-areas-options>

        <calculate-concentric-reachable-areas-settings>
        </calculate-concentric-reachable-areas-settings>
    </datasource>

Save the «Service.xml» file and rerun the Tomcat service,
From now on, whenever you call the WebService, the user should call one of the two resources in a query, indicating in the <GraphName> parameter the alias that has been defined previously in the <name> tag. If no alias is passed, the source defined in the iti.graphname parameter will be used by default.

Prev	Up	Next
	Home

Web Services documentation of Geoconcept Web - Web Services

Basic principles

Availability

Version change

V2

Parameters / properties

SOAP

REST

Possible responses

V2

Parameters / properties

SOAP

REST

Possible responses

V1

Parameters / properties

SOAP

REST

Possible responses

FAQ