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

Reverse geocoding example 

{
        "url":"https://api.geoconcept.com/EU/GCW/geoconcept-web/api/lbs/reverseGeocoding/v4.json",
        "type":"GET",
        "params": {
                "locations": {
                        "sample":"14.411633,50.086454;-0.127515,51.503264;13.377888,52.516224;21.014335,52.225451"
                },
                "srs": {
                        "sample":"epsg:4326"
                },
                "maxDistance": {
                        "sample":"1000"
                },
                "maxDistanceBetweenCandidates": {
                        "sample":"100"
                },
                "maxCandidates": {
                        "sample":"2"
                },
                "fields": {
                        "sample":"Postcode left; Postcode right"
                }

        }
}

Parameters / properties

Input

parameter description optional default

srs

projection (EPSG code such as epsg:4326 or wgs84)

yes

locations

Coordinates for points separated by “,”. Pair of XY coordinates are separated by “;”.

no

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

yes

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 meters) between each candidate.
if the parameter is passed, it is advisable to assign a value that is significantly higher than 1 (in meters).

yes

100

fields

List of fields to include in the response, separated by a ; character
Available fields are:
End right number, Begin right number, Begin left number, End left number, Iso country code,
Country, Reverse geocoding name, Postcode, Postcode left, Postcode right, City name,
City name left, City name right, Provider link id, TollPayPoint, Route type, Ramp,
Urban, Tunnel, Toll, Bicycles, Automobiles, Frontage, Bridge

yes

[]

Output

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

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)

addresses

0/unlimited

list of (candidate) addresses returned

Candidates returned (addresses)

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 meters) between the candidate returned and the start point

coordinates

string

1/1

Coordinates of the address

streetSide

string

"right" or "left"

fieldsValues

string

values for the requested fields on the street found

Possible returns

Example of a correct reverse geocoding (status is OK)  

{
    "status": "OK",
    "reverseGeocodingResults":[
    {
      "location": "14.411633,50.086454",
      "addresses":[
      {
        "addressLine": "KARLŮV MOST",
        "postCode": "118 00",
        "city": "PRAHA 1",
        "country": "Česko",
        "distanceMetersToLocation": 0.61,
        "coordinates": "14.411635,50.086459",
        "streetSide": "Left",
        "fieldsValues":["118 00", "118 00"]
      },
      {
        "addressLine": "KARLŮV MOST",
        "postCode": "118 00",
        "city": "PRAHA 1",
        "country": "Česko",
        "distanceMetersToLocation": 40.46,
        "coordinates": "14.41108,50.08653",
        "streetSide": "Left",
        "fieldsValues":["118 00", "118 00"]
      }
      ]
    },
    {
      "location": "-0.127515,51.503264",
      "addresses":[
      {
        "addressLine": "9 DOWNING STREET",
        "postCode": "SW1A 2",
        "city": "SW1",
        "country": "England",
        "distanceMetersToLocation": 6.24,
        "coordinates": "-0.127521,51.503208",
        "streetSide": "Right",
        "fieldsValues":["SW1A 2", "SW1A 2"]
      },
      {
        "addressLine": "10 DOWNING STREET",
        "postCode": "SW1A 2",
        "city": "SW1",
        "country": "England",
        "distanceMetersToLocation": 7.11,
        "coordinates": "-0.12757,51.50321",
        "streetSide": "Right",
        "fieldsValues":["SW1A 2", "SW1A 2"]
      }
      ]
    },
    {
      "location": "13.377888,52.516224",
      "addresses":[
      {
      "addressLine": "PARISER PLATZ",
      "postCode": "10117",
      "city": "MITTE",
      "country": "Deutschland",
      "distanceMetersToLocation": 8.04,
      "coordinates": "13.377873,52.516296",
      "streetSide": "Right",
      "fieldsValues":["10117", "10117"]
      },
      {
      "addressLine": "PARISER PLATZ",
      "postCode": "10117",
      "city": "MITTE",
      "country": "Deutschland",
      "distanceMetersToLocation": 9.46,
      "coordinates": "13.3778,52.51629",
      "streetSide": "Right",
      "fieldsValues":["10117", "10117"]
      }
      ]
    },
    {
      "location": "21.014335,52.225451",
      "addresses":[
      {
        "addressLine": "ULICA MARSZAŁKOWSKA",
        "postCode": "00-683",
        "city": "ŚRÓDMIEŚCIE",
        "country": "Polska",
        "distanceMetersToLocation": 8.3,
        "coordinates": "21.014221,52.225425",
        "streetSide": "Right",
        "fieldsValues":["00-683", "00-683"]
      },
      {
        "addressLine": "ULICA MARSZAŁKOWSKA",
        "postCode": "00-545",
        "city": "ŚRÓDMIEŚCIE",
        "country": "Polska",
        "distanceMetersToLocation": 9.92,
        "coordinates": "21.014471,52.225482",
        "streetSide": "Left",
        "fieldsValues":["00-545", "00-545"]
      }
      ]
    }
    ],
    "fieldsNames":[
      "Postcode left",
      "Postcode right"
    ]
}

Case of a query that does not snap (status is ERROR)  

An error append : (500) Internal Server Error
ServiceException: Error in reverse geocoding computation
Error in smartrouting
Failed to execute ReverseGeocode
com.geoconcept.smartrouting.SmartRoutingNativeException: failed to connect { 14.411633, 50.086454, 0.000000 }
failed to connect { 14.411633, 50.086454, 0.000000 }

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?

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, the value assigned by default is 1.

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, the value assigned by default is 100. There is a significant risk of not having any candidates returned at all.

Prev  Up  Next
  Home