Pöördgeokodeerimise juhend

Praktiline juhend näidetega: koordinaatidest lähima aadressi leidmine, väljundvormingud, detail-režiim ja koordinaatide järjekord eri vormingutes.

Endpoint ja meetodid

Kasutab GET- ja POST-meetodit (POST puhul application/x-www-form-urlencoded). NB: POST-i korral peab key olema päringustringis (URL-is); ainult vormikehas antud võtit võtmekontroll ei näe ja vastus on 403.

Parameetrite koondtabel

Andmekogu gl=ee_lt_lv (Eesti+Läti+Leedu) on praegu ainus seadistatud andmekogu; teenus on s=ADDRESS (või s=ADDRESS_reverse: komponendid tagurpidi, vt allpool).

Esimene päring

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 on sisendpunkti ja leitud aadressi vaheline kaugus meetrites (väärtus võib tulla eksponentkujul, nt 4.69E-4 = 0,47 mm). placemark on üks objekt (mitte massiiv). name kordab sisendkoordinaate.

Kuidas vaste valitakse

Iga sisendkoordinaadi kohta tuleb täpselt üks vaste. Mitu punkti saab küsida ühe päringuga, korrates parameetrit q; vastused on samas järjekorras.

• Kui lähim aadressipunkt (maja) on punktist kuni umbes 300 m kaugusel, tagastatakse maja-aadress.
• Kui maja lähedal ei ole (mets, põld, veekogu, maantee), tagastatakse haldusüksuse tase: Eestis küla või alevik, Lätis pagasts või linn, Leedus seniūnija koos omavalitsusega.
• Punkt, mis jääb kõigist aadressidest ja haldusüksustest kaugele (näiteks avameri), annab riigitaseme või tühja komponentide loendi (AddressLines: []).

Komponendid tagurpidi (s=ADDRESS_reverse)

Sufiks _reverse teenuse ID-l pöörab address-stringi komponentide järjekorra; täpsem enne: sobib otse kuvamiseks või lühendamiseks. Koordinaadid, distance ja struktureeritud AddressLines (detail) ei muutu. Sufiks on väiketähtedega (ADDRESS_REVERSE annab 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] }
    }
  }
]

Sama päring s=ADDRESS-iga annab "EE, Tartu maakond, Tartu linn, Tartu linn, Muuseumi tee 2". Töötab ka /rgc4_lyh-l ("Muuseumi tee 2, Tartu, Tartu, Tartumaa, EE").

Aadressikomponendid (detail)

Vaikimisi tagastatakse vaid aadressitekst, koordinaadid ja kaugus. Struktureeritud komponentide saamiseks lisa detail (ja kasuta 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] }
    }
  }
]

Läti ja Leedu komponendid

Läti ja Leedu punktidel on tüübikoodid samad, aga koosseis erineb:

• A4, A6 ja A8 Läti ja Leedu vastustes ei esine; korterit ei ole pöördgeokodeerimise vastuses ühelgi riigil.
• Läti aadressil võib A7 olla ka maja nimi (Riņņi), mitte number.
• POSTCODE on ilma riigiprefiksita (2127, mitte LV-2127).
• Tänavata maja aadressitekstis on maja nimi asula järel (…, Vecates pag., Riņņi); Leedus on tänavata maja kuju …, Matukų k. 11.

Väljundvormingud

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>

Erinevalt geokodeerimisest pole pöördgeokodeerimise xml2-s <AddressLines> ümbriselementi: <AddressLine> on otse <AddressDetails> all.

Koordinaatide järjekord

Sisend q on alati lat,lon (N,E).

ads_liik_staatus

Aadressi liik/staatus XML, aadress eestikeelsete väljadena, koos kaugusega:

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>

Millal mida kasutada

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"} ]

Läti ja Leedu AADRESS_ID sobib otse edasi: geokodeerija aidq=true päringusse (gl=lv / gl=lt) ja tasandiprefiksiga ka aadressikataloogi.

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

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

Veakäsitlus

Näited galeriis

• Leia lähim aadress
• Lähima esinduse leidmine
• Aadressivalija valmiskomponent