Reverse geocoding guide

Practical guide with examples: finding the nearest address from coordinates, output formats, detail mode and coordinate order across formats.

Endpoint and methods

Uses the GET and POST methods (POST with application/x-www-form-urlencoded). NB: with POST the key must be in the query string (the URL); a key given only in the form body is not seen by the key check and the response is 403.

Parameter reference

Dataset gl=ee_lt_lv (Estonia+Latvia+Lithuania) is currently the only configured dataset; the service is s=ADDRESS (or s=ADDRESS_reverse: components reversed, see below).

First request

curl "https://pump.elemroot.com/rgc4/revgeocode?q=58.3957739405547,26.7462826320901&gl=ee_lt_lv&s=ADDRESS&key=docs_382d376eaaa6d004b7b93b7d"

[
  {
    "distance": 4.6902068828416404E-4,
    "name": "58.3957739405547,26.7462826320901",
    "placemark": {
      "address": "EE, Tartu maakond, Tartu linn, Tartu linn, Muuseumi tee 2",
      "point": { "coordinates": [26.74628262527919, 58.39577393830106] }
    }
  }
]

distance is the distance between the input point and the found address in metres (the value may come in exponent form, e.g. 4.69E-4 = 0.47 mm). placemark is one object (not an array). name echoes the input coordinates.

How the match is chosen

Every input coordinate returns exactly one match. Several points can be queried in one request by repeating the q parameter; responses come back in the same order.

• If the nearest address point (a building) is within roughly 300 m, the building address is returned.
• If there is no building nearby (forest, field, water, highway), an administrative level is returned: a village or small town in Estonia, a pagasts or town in Latvia, a seniūnija with its municipality in Lithuania.
• A point far from all addresses and administrative units (open sea, for example) returns the country level or an empty component list (AddressLines: []).

Components reversed (s=ADDRESS_reverse)

The _reverse suffix on the service ID reverses the component order of the address string; most specific first: handy for direct display or shortening. Coordinates, distance and the structured AddressLines (detail) do not change. The suffix is lower case (ADDRESS_REVERSE returns 500).

curl "https://pump.elemroot.com/rgc4/revgeocode?q=58.3957739405547,26.7462826320901&gl=ee_lt_lv&s=ADDRESS_reverse&key=docs_382d376eaaa6d004b7b93b7d"

[
  {
    "distance": 4.6902068828416404E-4,
    "name": "58.3957739405547,26.7462826320901",
    "placemark": {
      "address": "Muuseumi tee 2, Tartu linn, Tartu linn, Tartu maakond, EE",
      "point": { "coordinates": [26.74628262527919, 58.39577393830106] }
    }
  }
]

The same request with s=ADDRESS gives "EE, Tartu maakond, Tartu linn, Tartu linn, Muuseumi tee 2". Works on /rgc4_lyh too ("Muuseumi tee 2, Tartu, Tartu, Tartumaa, EE").

Address components (detail)

By default only address text, coordinates and distance are returned. For structured components add detail (and use json2/xml2):

curl "https://pump.elemroot.com/rgc4/revgeocode?q=58.3957739405547,26.7462826320901&gl=ee_lt_lv&s=ADDRESS&output=json2&detail&key=docs_382d376eaaa6d004b7b93b7d"

[
  {
    "distance": 4.6902068828416404E-4,
    "name": "58.3957739405547,26.7462826320901",
    "placemark": {
      "address": "EE, Tartu maakond, Tartu linn, Tartu linn, Muuseumi tee 2",
      "AddressDetails": {
        "AddressLines": [
          { "Type": "A0",      "Value": "Eesti Vabariik" },
          { "Type": "A1",      "Value": "Tartu maakond" },
          { "Type": "A2",      "Value": "Tartu linn" },
          { "Type": "A3",      "Value": "Tartu linn" },
          { "Type": "A5",      "Value": "Muuseumi tee" },
          { "Type": "A7",      "Value": "2" },
          { "Type": "POSTCODE","Value": "60532" },
          { "Type": "A1_EHAK", "Value": "0079" },
          { "Type": "A2_EHAK", "Value": "0793" },
          { "Type": "A3_EHAK", "Value": "8151" }
        ]
      },
      "point": { "coordinates": [26.74628262527919, 58.39577393830106] }
    }
  }
]

Latvian and Lithuanian components

Latvian and Lithuanian points use the same type codes, but the set differs:

• A4, A6 and A8 do not appear in Latvian or Lithuanian responses; no country returns apartments in reverse geocoding.
• On Latvian addresses A7 can also be a house name (Riņņi), not a number.
• POSTCODE comes without the country prefix (2127, not LV-2127).
• For a house without a street the house name follows the settlement in the address text (…, Vecates pag., Riņņi); in Lithuania the form is …, Matukų k. 11.

Output formats

output: json, json2, xml, xml2, kml, ads_liik_staatus.

xml2

curl "https://pump.elemroot.com/rgc4/revgeocode?q=58.3957739405547,26.7462826320901&gl=ee_lt_lv&s=ADDRESS&output=xml2&detail&key=docs_382d376eaaa6d004b7b93b7d"

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<kml xmlns="http://earth.google.com/kml/2.0">
<Response>
<name>58.3957739405547,26.7462826320901</name>
<distance>4.6902068828416404E-4</distance>
<Placemark>
<Point><coordinates>58.39577393830106,26.74628262527919</coordinates></Point>
<address>EE, Tartu maakond, Tartu linn, Tartu linn, Muuseumi tee 2</address>
<AddressDetails>
<AddressLine Type="A0">Eesti Vabariik</AddressLine>
<AddressLine Type="A1">Tartu maakond</AddressLine>
<AddressLine Type="A2">Tartu linn</AddressLine>
<AddressLine Type="A3">Tartu linn</AddressLine>
<AddressLine Type="A5">Muuseumi tee</AddressLine>
<AddressLine Type="A7">2</AddressLine>
<AddressLine Type="POSTCODE">60532</AddressLine>
<AddressLine Type="A1_EHAK">0079</AddressLine>
<AddressLine Type="A2_EHAK">0793</AddressLine>
<AddressLine Type="A3_EHAK">8151</AddressLine>
</AddressDetails>
</Placemark>
</Response>
</kml>

Unlike geocoding, reverse geocoding xml2 has no <AddressLines> wrapper: <AddressLine> elements sit directly under <AddressDetails>.

Coordinate order

Input q is always lat,lon (N,E).

ads_liik_staatus

Address type/status XML, address as Estonian-named fields, with distance:

curl "https://pump.elemroot.com/rgc4/revgeocode?q=58.3957739405547,26.7462826320901&gl=ee_lt_lv&s=ADDRESS&output=ads_liik_staatus&detail&key=docs_382d376eaaa6d004b7b93b7d"

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<aadressideNimekiri>
<aadress>
<aadressSisse>58.3957739405547,26.7462826320901</aadressSisse>
<kaugus>4.6902068828416404E-4</kaugus>
<vaste>
<maakondEhak>0079</maakondEhak>
<maakond>Tartu maakond</maakond>
<omavalitsusEhak>0793</omavalitsusEhak>
<omavalitsus>Tartu linn</omavalitsus>
<asustusyksusEhak>8151</asustusyksusEhak>
<asustusyksus>Tartu linn</asustusyksus>
<liikluspind>Muuseumi tee</liikluspind>
<aadressinumber>2</aadressinumber>
<sihtnumber>60532</sihtnumber>
<aadressValja>EE, Tartu maakond, Tartu linn, Tartu linn, Muuseumi tee 2</aadressValja>
<koordinaadid>26.74628262527919,58.39577393830106</koordinaadid>
</vaste>
</aadress>
</aadressideNimekiri>

Which combination to use

curl "https://pump.elemroot.com/rgc4/revgeocode?q=58.3957739,26.7462826&gl=ee_lt_lv_aid&s=ADDRESS&output=json2&detail=true&key=docs_382d376eaaa6d004b7b93b7d"

"AddressLines": [ …, {"Type": "A7", "Value": "2"}, {"Type": "POSTCODE", "Value": "60532"}, …, {"Type": "AADRESS_ID", "Value": "3069760"} ]

curl "https://pump.elemroot.com/rgc4/revgeocode?q=57.520503,25.390738&gl=ee_lt_lv_aid&s=ADDRESS&output=json2&detail=true&key=docs_382d376eaaa6d004b7b93b7d"

"AddressLines": [ …, {"Type": "A7", "Value": "195 k-1"}, {"Type": "POSTCODE", "Value": "4201"}, {"Type": "AADRESS_ID", "Value": "101020361"} ]

A Latvian or Lithuanian AADRESS_ID can be used directly: pass it to geocoding with aidq=true (gl=lv / gl=lt), and with a level prefix also to the address catalogue.

# 1) point -> address text
curl "https://pump.elemroot.com/rgc4/revgeocode?q=58.3957739,26.7462826&gl=ee_lt_lv&s=ADDRESS&key=docs_382d376eaaa6d004b7b93b7d"

# 2) address text -> AADRESS_ID
curl "https://pump.elemroot.com/jgc_rest/geocode?q=Muuseumi+tee+2,+Tartu+linn&gl=ee_aid&output=json2&key=docs_382d376eaaa6d004b7b93b7d"

Error handling

Examples in the gallery

• Find the nearest address
• Finding the nearest location
• Address picker component