Address search guide

Practical guide with examples: how to send requests, choose outputs and use all service features. Each section includes a runnable curl example and a sample response.

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

Datasets (gl):

Repeat gl to search multiple datasets at once (e.g. &gl=ee_aid&gl=lv).

First request

curl "https://pump.elemroot.com/jgc_rest/geocode?q=Muuseumi+tee+2&gl=ee_aid&output=json&key=docs_382d376eaaa6d004b7b93b7d"

[
  {
    "name": "Muuseumi tee 2",
    "placemark": [
      {
        "address": "Eesti Vabariik, Tartu maakond, Tartu linn, Tartu linn, Muuseumi tee 2",
        "AddressDetails": { "Accuracy": "8" },
        "LatLonBox": {
          "east": 26.756282629776482,
          "south": 58.39077394011176,
          "north": 58.40077393988824,
          "west": 26.736282630223517
        },
        "point": { "coordinates": [26.74628263, 58.39577394] },
        "relevance": 0.1004990025510281
      }
    ]
  }
]

The response is an array: one object per input address. Field name echoes the input; placemark contains matches sorted by relevance (highest relevance first). Coordinates are in [E, N] order (for EPSG:4326: [longitude, latitude]).

Refining with postal code

The same street name may exist in several places in Estonia. To find the correct address in the right place, add a postal code (5 digits) to the input; the service detects it and filters matches to the correct region.

curl "https://pump.elemroot.com/jgc_rest/geocode?q=Muuseumi+tee+2&gl=ee_aid&output=json2&maxcount=5&key=docs_382d376eaaa6d004b7b93b7d"

Eesti Vabariik, Tartu maakond, Tartu linn, Tartu linn, Muuseumi tee 2      (postal code 60532)
Eesti Vabariik, Harju maakond, Rae vald, Lagedi alevik, Muuseumi tee 2     (postal code 75303)
Eesti Vabariik, Tartu maakond, Tartu linn, Tartu linn, Muuseumi tee 2/1    (postal code 60532)

curl "https://pump.elemroot.com/jgc_rest/geocode?q=Muuseumi+tee+2,+75303&gl=ee_aid&output=json2&srs=EPSG:3301&key=docs_382d376eaaa6d004b7b93b7d"

[
  {
    "name": "Muuseumi tee 2, 75303",
    "placemark": [
      {
        "address": "Eesti Vabariik, Harju maakond, Rae vald, Lagedi alevik, Muuseumi tee 2",
        "AddressDetails": {
          "AddressLines": [
            { "Type": "A0",           "Value": "Eesti Vabariik" },
            { "Type": "A1",           "Value": "Harju maakond" },
            { "Type": "A2",           "Value": "Rae vald" },
            { "Type": "A3",           "Value": "Lagedi alevik" },
            { "Type": "A5",           "Value": "Muuseumi tee" },
            { "Type": "A7",           "Value": "2" },
            { "Type": "A1_EHAK",      "Value": "0037" },
            { "Type": "A2_EHAK",      "Value": "0653" },
            { "Type": "A3_EHAK",      "Value": "4043" },
            { "Type": "POSTCODE",     "Value": "75303" },
            { "Type": "AADRESS_ID",   "Value": "772374" },
            { "Type": "A_STAATUS_ID", "Value": "1" }
          ],
          "Accuracy": "8"
        },
        "point": { "coordinates": [553474.2797853436, 6583771.550346661] },
        "relevance": 0.09405935760739681
      }
    ]
  }
]

Output formats

Same request with different output values.

xml

curl "https://pump.elemroot.com/jgc_rest/geocode?q=Muuseumi+tee+2&gl=ee_aid&output=xml&key=docs_382d376eaaa6d004b7b93b7d"

<?xml version='1.0' encoding='UTF-8'?>
<kml xmlns="http://earth.google.com/kml/2.0">
  <Response>
    <name>Muuseumi tee 2</name>
    <Placemark>
      <address>Eesti Vabariik, Tartu maakond, Tartu linn, Tartu linn, Muuseumi tee 2</address>
      <LatLonBox>
        <north>58.40077393988824</north><south>58.39077394011176</south>
        <east>26.756282629776482</east><west>26.736282630223517</west>
      </LatLonBox>
      <Point><coordinates>26.74628263,58.39577394</coordinates></Point>
      <relevance>0.1004990025510281</relevance>
      <AddressDetails Accuracy="8" />
    </Placemark>
  </Response>
</kml>

kml (Google Earth)

curl "https://pump.elemroot.com/jgc_rest/geocode?q=Muuseumi+tee+2&gl=ee_aid&output=kml&key=docs_382d376eaaa6d004b7b93b7d"

Same structure as xml, but Content-Type is application/vnd.google-earth.kml+xml, suitable for Google Earth / map apps directly.

json2 / xml2: flat structured address

json2 and xml2 return the address as a list (AddressLines). Each line is a typed component (Type, optional Subtype, Value). Dataset ee_aid uses type codes A0, A1, …

curl "https://pump.elemroot.com/jgc_rest/geocode?q=Muuseumi+tee+2&gl=ee_aid&output=json2&key=docs_382d376eaaa6d004b7b93b7d"

[
  {
    "name": "Muuseumi tee 2",
    "placemark": [
      {
        "address": "Eesti Vabariik, 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": "A1_EHAK",      "Value": "0079" },
            { "Type": "A2_EHAK",      "Value": "0793" },
            { "Type": "A3_EHAK",      "Value": "8151" },
            { "Type": "POSTCODE",     "Value": "60532" },
            { "Type": "AADRESS_ID",   "Value": "3069760" },
            { "Type": "A_STAATUS_ID", "Value": "1" }
          ],
          "Accuracy": "8"
        },
        "LatLonBox": { "east": 26.756282629776482, "south": 58.39077394011176,
                       "north": 58.40077393988824, "west": 26.736282630223517 },
        "point": { "coordinates": [26.74628263, 58.39577394] },
        "relevance": 0.1004990025510281
      }
    ]
  }
]

Type code meanings:

XML equivalent (output=xml2) wraps lines in <AddressLines>:

<AddressDetails Accuracy="8">
  <AddressLines>
    <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>
  </AddressLines>
</AddressDetails>

ads_liik_staatus (address type and status)

For the Estonian address dataset there is a separate XML format ads_liik_staatus, returning the address as Estonian-named fields (EHAK codes, types, status, postal code, etc.):

curl "https://pump.elemroot.com/jgc_rest/geocode?q=Muuseumi+tee+2&gl=ee_aid&output=ads_liik_staatus&key=docs_382d376eaaa6d004b7b93b7d"

<?xml version='1.0' encoding='UTF-8'?>
<aadressideNimekiri>
  <aadress>
    <aadressSisse>Muuseumi tee 2</aadressSisse>
    <vaste>
      <aid>3069760</aid>
      <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>Eesti Vabariik, Tartu maakond, Tartu linn, Tartu linn, Muuseumi tee 2</aadressValja>
      <abStaatusId>1</abStaatusId>
      <vastavuseHeadus>Korras</vastavuseHeadus>
      <koordinaadid>26.74628263,58.39577394</koordinaadid>
      <relevantsus>0.1004990025510281</relevantsus>
      <latLonBox>
        <north>58.40077393988824</north><south>58.39077394011176</south>
        <east>26.756282629776482</east><west>26.736282630223517</west>
      </latLonBox>
    </vaste>
  </aadress>
</aadressideNimekiri>

Empty elements in the example (e.g. <korterinumber/>, <vaikekoht/>) are omitted for brevity. This format is available only when the server allows it for the dataset.

Coordinate reference systems

Default EPSG:4326 (WGS84, degrees). For the Estonian projected system (metres) use EPSG:3301 (L-EST97). The code is case-insensitive (epsg:3301 works) and the aliases wgs84 / l-est97 are accepted too; any other value (bare 3301, EPSG:3857) returns 400. We recommend the canonical form.

curl "https://pump.elemroot.com/jgc_rest/geocode?q=Muuseumi+tee+2&gl=ee_aid&srs=EPSG:3301&key=docs_382d376eaaa6d004b7b93b7d"

"point": { "coordinates": [660545.9498807918, 6476102.220117778] },
"LatLonBox": {
  "east": 661107.3382034153,  "south": 6475521.90091788,
  "north": 6476682.619832239, "west": 659984.3920757968
}

Bulk request

Multiple addresses at once: repeat q:

curl "https://pump.elemroot.com/jgc_rest/geocode?q=Muuseumi+tee+2&q=Ülikooli+18&gl=ee_aid&maxcount=1&key=docs_382d376eaaa6d004b7b93b7d"

[
  {
    "name": "Muuseumi tee 2",
    "placemark": [
      { "address": "Eesti Vabariik, Tartu maakond, Tartu linn, Tartu linn, Muuseumi tee 2",
        "AddressDetails": { "Accuracy": "8" },
        "point": { "coordinates": [26.74628263, 58.39577394] },
        "relevance": 0.1004990025510281 }
    ]
  },
  {
    "name": "Ülikooli 18",
    "placemark": [
      { "address": "Eesti Vabariik, Tartu maakond, Tartu linn, Tartu linn, Ülikooli tänav 18",
        "AddressDetails": { "Accuracy": "8" },
        "point": { "coordinates": [26.71952943, 58.38076991] },
        "relevance": 0.09787157650387346 }
    ]
  }
]

Each input address gets its own object in the same order.

Address lookup by id (aidq)

If you have stored an address id (AADRESS_ID: the same number returned in gl=ee_aid responses), you can look up its address directly with aidq=true: every q value is then an id instead of address text. The response is a regular geocoding response (all output formats and srs/rs apply), so existing parsing works unchanged.

curl "https://pump.elemroot.com/jgc_rest/geocode?q=3069760&gl=ee_aid&aidq=true&output=json2&key=docs_382d376eaaa6d004b7b93b7d"

[
  {
    "name": "3069760",
    "placemark": [
      { "address": "Eesti Vabariik, Tartu maakond, Tartu linn, Tartu linn, Muuseumi tee 2",
        "AddressDetails": { "AddressLines": [ …, { "Type": "AADRESS_ID", "Value": "3069760" }, … ] },
        "point": { "coordinates": [26.74628263, 58.39577394] } }
    ]
  }
]

• The response contains exactly the point whose AADRESS_ID equals the requested id (normally 1 match).
• An unknown or non-numeric id yields 0 results ("name" present, no placemark); not an error.
• q remains repeatable in id mode: several ids per request (see bulk).
• Supported datasets: ee, ee_aid, lv, lt. For Estonia prefer gl=ee_aid so the id is also visible in ordinary responses. For Latvia and Lithuania the AADRESS_ID is already present with plain gl=lv / gl=lt; lv_aid and lt_aid do not exist and return 400.
• On /jgc_rest_lyh an apartment id returns the address of its building, because the short service dataset has no apartment level. Use /jgc_rest when you need apartment precision.

curl "https://pump.elemroot.com/jgc_rest/geocode?q=101020361&gl=lv&aidq=true&output=json2&key=docs_382d376eaaa6d004b7b93b7d"

[
  {
    "name": "101020361",
    "placemark": [
      { "address": "Latvija, Valmieras nov., Valmiera, Jumaras iela 195 k-1",
        "AddressDetails": {
          "AddressLines": [ …, { "Type": "A7", "Value": "195 k-1" },
                            { "Type": "POSTCODE", "Value": "4201" },
                            { "Type": "AADRESS_ID", "Value": "101020361" } ],
          "Accuracy": "8" },
        "point": { "coordinates": [25.390738, 57.520503] } }
    ]
  }
]

Multiple datasets

Search multiple datasets at once: repeat gl. Results are grouped by address and sorted by relevance.

curl "https://pump.elemroot.com/jgc_rest/geocode?q=Pärnu+mnt+1&gl=ee_aid&gl=lv&key=docs_382d376eaaa6d004b7b93b7d"

Searching Estonian addresses

The search handles both the official address and everyday spellings: the table below shows which forms return the same answer.

What the punctuation means in an Estonian address:

• A hyphen separates the building and the apartment: Anne tn 1-1 is building 1, apartment 1; in the response the building is row A7 and the apartment A8. The same applies to named addresses: Kivimõisa-2 is apartment 2 of the Kivimõisa farm.
• A slash in the house number means a parallel number of one building, not an apartment: Muuseumi tee 2/1 is a separate building (A7=2/1).
• A letter is part of the house number: Anne tn 14a (A7=14a).
• The search is lenient with input: an apartment is also found as 1/1 or krt 1; when the requested apartment does not exist, the building is returned.

Searching Latvian addresses

The Latvian address model differs from the Estonian one: the building name and number share one field, and the block (korpuss) sits inside it. Search handles every common spelling: the table below shows which forms return the same result.

• Diacritics are optional: Rinni, Vecates pagasts finds Riņņi.
• In rural areas the village and the building name share one address part: Dzērbene Ciedras means the village Dzērbene and the building Ciedras.
• A bare building name without context is found, but the answer is often ambiguous; there are many identically named holdings. Adding the village or the pagasts narrows it down.
• Fields in AddressLines: street A5, building number together with the block A7, apartment A8. A4 and A6 do not appear in Latvian responses.
• gl=lv responses always carry AADRESS_ID: there is no separate lv_aid dataset.

Searching Lithuanian addresses

A Lithuanian address consists of the municipality (savivaldybė), the eldership (seniūnija, often absent in cities), the settlement, the street and the house number; the block is part of the house number (2A K1). The search accepts both the official postal form and everyday spellings; the table below shows which forms return the same answer.

• Diacritics are optional: Perkuno g. 2A K1, Rokiskis finds Perkūno g. 2A K1.
• 2A-1 means apartment 1 in house 2A, not a block: a block is written 2A K1.
• The eldership comes back as line A2; in cities without elderships the line is absent.
• Administrative unit names are returned in the register's abbreviated form (Vilniaus miesto sav., Kartenos sen.); both the abbreviation and the full word work as search terms.
• Settlements are returned in the official register address form: towns in the nominative (Kaunas, Gelvonai), villages and farmsteads in the genitive with the type abbreviation (Ežeraičių k., Lapkalnio vs.). Both forms work in queries — Ežeraičiai finds Ežeraičių k.. This also distinguishes same-named settlements (town Gelvonai vs village Gelvonų k.) directly in the result list.
• Settlements with the same name in the same eldership (for example a village and a farmstead) give several results; the type abbreviation (Lapkalnio vs. 1) narrows it down.
• Fields in AddressLines: street A5, house number including the block A7, apartment A8. A4 and A6 do not occur in Lithuanian responses.
• A gl=lt response carries AADRESS_ID at every level: house and apartment (Registrų centras object code) as well as municipality, eldership, settlement and street (register code); the same code works with aidq=true; there is no separate lt_aid dataset.

Result count and accuracy

By default up to 10 matches per address are returned. Limit with maxcount:

curl "https://pump.elemroot.com/jgc_rest/geocode?q=Tartu&gl=ee_aid&maxcount=3&key=docs_382d376eaaa6d004b7b93b7d"

Matches are sorted by relevance. Each match includes:

Accuracy values:

These are the values that occur in the Estonian dataset; Latvia and Lithuania use the same scale with their own administrative levels (a building is 8 there as well).

Location bias (ll + spn)

Restrict matches to a geographic window. ll is the centre (lat,lon), spn the window size (spanLat,spanLon); the window is ll ± spn/2.

curl "https://pump.elemroot.com/jgc_rest/geocode?q=Kesktee&gl=ee_aid&key=docs_382d376eaaa6d004b7b93b7d"
# first match: Harju maakond, Tallinn, Pirita linnaosa, Kesktee

curl "https://pump.elemroot.com/jgc_rest/geocode?q=Kesktee&gl=ee_aid&ll=58.38,26.72&spn=0.2,0.4&key=docs_382d376eaaa6d004b7b93b7d"
# first match: Tartu maakond, Kastre vald, Haaslava küla, Kesktee

The window filters: matches outside it are not returned. To keep them and re-rank yourself, omit the window and use a larger maxcount.

Autocomplete (ac)

For search-as-you-type enable ac: the engine expands the last token of the input:

curl "https://pump.elemroot.com/jgc_rest/geocode?q=Muuseu&gl=ee_aid&output=json2&ac&maxcount=10&key=docs_382d376eaaa6d004b7b93b7d"

Behaviour is level-based: the next level's continuations are offered:

• A street without a number → its houses; a house number → that house's apartments. If maxcount leaves room, the rest is filled with next-level rows: q=Pae tn 43 → 43, 43b, 43-1, 43-2 …
• Word order does not matter: Kannikese 33, Tartu linn and Tartu linn, Kannikese 33 return the same list.
• Termination signal: a space or hyphen after the number (q=Kannikese 33  or 33-) limits the list to that house: 33a is no longer offered.

Skipping words (st)

When the input has unknown or extra words, allow skipping them with st (maximum skipped words):

curl "https://pump.elemroot.com/jgc_rest/geocode?q=ettevõte+OÜ+Muuseumi+tee+2&gl=ee_aid&st=2&key=docs_382d376eaaa6d004b7b93b7d"

Higher st yields more matches but may reduce precision.

Extended data (xd)

xd=true adds an ExtendedData block to each match: how the input was interpreted (matched words, recognised types, unknown tokens), input flat number, postal code, etc.

curl "https://pump.elemroot.com/jgc_rest/geocode?q=Muuseumi+tee+2-1&gl=ee_aid&xd=true&st=1&key=docs_382d376eaaa6d004b7b93b7d"

"ExtendedData": {
  "recognizedTokens": [
    { "start": 15, "end": 16, "token": "1", "skipped": 0 }
  ],
  "unrecognizedTokens": [],
  "isCharsimApplied": false,
  "isPostcodeSkipped": false,
  "matchedTokens": [
    { "start": 0,  "end": 12, "token": "Muuseumi tee", "skipped": 0 },
    { "start": 13, "end": 14, "token": "2",            "skipped": 0 }
  ],
  "skippedTokenCount": 0,
  "inputFlatNumber": "1"
}

Rule sets (rs)

Parameter rs selects a server rule set. Two supported values:

rs=reverse: the address string comes with its components in reverse order (most specific first); the structured AddressLines and everything else stay the same. Works on the _lyh service and on the LV/LT datasets too. Handy for direct display:

curl "https://pump.elemroot.com/jgc_rest/geocode?q=Muuseumi+tee+2,+Tartu&gl=ee_aid&rs=reverse&maxcount=1&key=docs_382d376eaaa6d004b7b93b7d"

"address": "Muuseumi tee 2, Tartu linn, Tartu linn, Tartu maakond, Eesti Vabariik"

Without rs: "Eesti Vabariik, Tartu maakond, Tartu linn, Tartu linn, Muuseumi tee 2". Same meaning as s=ADDRESS_reverse in reverse geocoding.

rs=A2A3: adds all A3-level sub-places under an A2-level (municipality) match (Estonian dataset only). Useful for place-picker interfaces: a single request returns a municipality together with all of its settlements, without separate catalogue requests. The row count is capped by maxcount (default 10):

curl "https://pump.elemroot.com/jgc_rest/geocode?q=Saaremaa&gl=ee_aid&rs=A2A3&key=docs_382d376eaaa6d004b7b93b7d"

The value is case-sensitive (REVERSE returns 400); an unknown rs value returns 400.

XAL2 type replacement (replaceType)

In json2/xml2 output you can rename component types. Parameter form old new (space-separated pair), repeatable. For example rename type A5 (thoroughfare) to street:

curl "https://pump.elemroot.com/jgc_rest/geocode?q=Muuseumi+tee+2&gl=ee_aid&output=json2&replaceType=A5+street&key=docs_382d376eaaa6d004b7b93b7d"

{ "Type": "street", "Value": "Muuseumi tee" }

JSONP (callback)

The service returns Access-Control-Allow-Origin: *; in a modern browser plain fetch() is enough. JSONP remains for older clients.

For JSONP add callback: the response is wrapped in a function call:

curl "https://pump.elemroot.com/jgc_rest/geocode?q=Muuseumi+tee+2&gl=ee_aid&callback=naita&key=docs_382d376eaaa6d004b7b93b7d"

naita && naita([{"name":"Muuseumi tee 2","placemark":[{"address":"Eesti Vabariik, Tartu maakond, Tartu linn, Tartu linn, Muuseumi tee 2","AddressDetails":{"Accuracy":"8"},"point":{"coordinates":[26.74628263,58.39577394]},"relevance":0.1004990025510281}]}])

Content-Type is then application/javascript.

Which combination to use

Common tasks and the parameter combination for each. Every row is verified live.

curl "https://pump.elemroot.com/jgc_rest/geocode?q=Muuseu&gl=ee_aid&output=json2&ac&maxcount=10&key=docs_382d376eaaa6d004b7b93b7d"

curl "https://pump.elemroot.com/jgc_rest/geocode?q=Muuseumi+tee+2&q=%C3%9Clikooli+18&q=Kannikese+33,+Tartu&gl=ee_aid&output=json2&maxcount=1&key=docs_382d376eaaa6d004b7b93b7d"

The response contains three objects, in the same order as the input.

Error handling

curl -i "https://pump.elemroot.com/jgc_rest/geocode?q=Tartu&gl=puudub&key=docs_382d376eaaa6d004b7b93b7d"

HTTP/1.1 400 Bad Request
Content-Type: text/html;charset=utf-8

<html><head><title>Apache Tomcat - Error report</title> ... </head>
<body> ... No dataset puudub ... </body></html>

The error body is a Tomcat HTML error page containing the message (here "No dataset puudub").

Examples in the gallery

• Address search on the L-EST97 raster map
• Address search on the Elemroot raster map
• One search: Estonian, Latvian and Lithuanian addresses
• Address search on the Elemroot vector map
• Geocoding a list of addresses
• Address field in a checkout form