Aadressivaliku juhend

Balti aadressikataloog (Eesti, Läti ja Leedu): päri aadress ID järgi, hangi aadressi ülemobjektide ahel ja sirvi aadressipuud kaskaad-valikutena. Riigi valib parameeter c=ee|lv|lt (vaikimisi Eesti).

Endpointid ja marsruutimine

Baas: https://pump.elemroot.com/Gazetter. Igal alateenusel on oma tee:

Kõik kolm endpointi võtavad lisaks riigiparameetri c (ee / lv / lt, vaikimisi ee): vt riikide peatükki.

Sama saab kutsuda ka parameetriga layer:

https://pump.elemroot.com/Gazetter/?key=docs_382d376eaaa6d004b7b93b7d&layer=getdescription&id=3069760

Väärtused: getdescription, getfillinfo, currentlayer. Ilma layer-ita tagastatakse {"success": false}.

Mõlemad vormid võtavad vastu ka POST-i (application/x-www-form-urlencoded). NB: key peab ka siis olema URL-is, mitte ainult vormikehas.

Riigid: Eesti, Läti, Leedu (parameeter c)

Gazetteer katab kolm riiki. Riigi valib parameeter c: ee (vaikimisi), lv või lt; tundmatu väärtus käitub nagu ee. Parameeter kehtib kõigil kolmel endpointil ja ID-d on riigisisesed: sama id tähendab eri riikides eri objekti, seega anna c kaasa ka getDescription / getFillInfo päringutele.

curl "https://pump.elemroot.com/Gazetter/layer/currentLayer/?key=docs_382d376eaaa6d004b7b93b7d&l=1&c=lv"

{
  "success": true,
  "addressList": [
    { "id": 1100016630, "nimi": "Aizkraukles nov." },
    { "id": 1100003028, "nimi": "Jelgava" },
    { "id": 1100003003, "nimi": "Rīga" }
  ]
}

Tasemed riigiti

Tasemeskaala l=1–6 on kõigil riikidel sama, aga sisu erineb ja tasemed ei ole omavahel samatähenduslikud. Kõige olulisem erinevus: Läti ja Leedu 1. tase on omavalitsus, Eestis on omavalitsus 2. tasemel: Lätis kaotati rajoonid 2009 ja Leedu apskritis ei kuulu ametlikku aadressi, seega maakonna-tasandit neil ei ole. Sama loogika kehtib 2. tasemel: Läti pagasts ja Leedu seniūnija ei ole omavalitsused, vaid omavalitsuse territoriaalsed allüksused.

Vormi ehitades arvesta riikide eripäradega:

• Leedu seniūnija on 2. tase: nagu Registrų centro ametlikus maa-aadressis. Kaskaad on l=1 savivaldybė → l=2 seniūnija → l=3 asula. Linnades seniūnijat ei ole (Vilnius, Kaunas, Klaipėda jt: register ise ei anna linnaaadressile seniūniją): seal on l=2 tühi ja asula tuleb otse l=3&p=<savivaldybė> pealt. Seniūnija tuleb getDescription väljas A2_NIMI. Kui samas seniūnijas on kaks samanimelist asulat, kannab nimi RC liigilühendit, nt "Lapkalnis (k.)" ja "Lapkalnis (vs.)".
• Läti valstspilsētad (Rīga, Jelgava jt) on 1. tasemel; 2. ja 3. taset neil ei ole, tänavad tulevad otse linna alt (l=4&p=<pilsēta>: Rīgal 1 811 tänavat). Rīga linnaosa (priekšpilsēta / rajons) ei ole aadressitase ega tule vastuses kaasa: VZD hoiab teda objekti atribuudina ja ametlik Läti aadress teda ei sisalda. Sama l=4&g= muster töötab novadu pilsētatel (2. tase).
• Ilma tänavata majad (mõlemas riigis, nt nimemajad ciemas): l=5&g=<asula>: täpselt nagu Eesti talude puhul.
• Puuduvate vahetasemete üldvõte: sondeeri valiku järel KÕIKI sügavamaid tasemeid (l+1…6) ja näita neid, mis vastavad success: true. Ainult kolme järgmise küsimisest ei piisa: Läti valstspilsēta all on nii tänavad (l=4) kui otse majad (l=5), st hüpe võib olla neli taset pikk. Tühi vastus sügavamal ei tähenda tupikut: küsi kõik läbi ja märgi vahelejääv tase kasutajale ära (nii teeb ka näidisrakendus).

ID-d ja väljad LV/LT vastustes

• Eesti id = AADRESS_ID (nagu seni). Läti/Leedu id = tasandiprefiks×10⁹ + riiklik registrikood (LV: VZD kods; LT: Registrų centras); nt Jelgava 1100003028 (tase 1, kods 100003028). ID-d on püsivad ja sobivad salvestamiseks; registrikoodi saab kätte väljast KOODAADRESS.
• getDescription LV/LT vastuses on komponendid samas A1_NIMI…A8_NIMI raamis (A4_NIMI ja A6_NIMI on seal alati null; A2_NIMI kannab Lätis pagasti/pilsēta ja Leedus seniūnija nime); Eesti-spetsiifilisi välju (A*_EHAK, A_STAATUS_ID, A5_NIMI_INIT) seal pole.
• Nimekirjad on riigikeelses tähestikujärjestuses (Jõgeva enne Järvat, Põlva enne Pärnut; LV/LT diakriitikud õiges kohas).
• Geokodeerija ID ja kataloogi ID on omavahel arvutatavad. Geokodeerimise (jgc_rest, gl=lv/gl=lt) vastuse AADRESS_ID on riiklik registrikood ilma tasandiprefiksita, kataloogi id aga prefiksiga: id = tasandiprefiks × 10⁹ + AADRESS_ID. Prefiksid: 1 = 1. tase (LV novads/valstspilsēta, LT savivaldybė), 2 = 2. tase (LV pagasts/pilsēta, LT seniūnija), 3 = asula, 5 = tänav, 7 = maja, 8 = korter. Vastassuunas annab sama numbri väli KOODAADRESS. Paljas AADRESS_ID ilma prefiksita annab success: false. Eesti ID-d ühtivad, seal prefiksit vaja ei ole.
  Näide: geokodeerija annab Läti majale AADRESS_ID 101020361 → kataloogis id=7101020361; sama maja korter 110001974 → id=8110001974. Ülemobjektide ahela (tänav, asula, novads) ID-d ei pea ise arvutama; need tulevad getFillInfo vastusest.

Parameetrite koondtabel

Aadress AADRESS_ID järgi (getDescription)

Tagastab kogu aadressikirje antud id (= AADRESS_ID) järgi. See on otsetee, kui sul on aadressi ID juba olemas: näiteks geokodeerimise väljundist (AADRESS_ID / <aid>; Eesti ID-d lähevad sisse muutmata, LV/LT ID-d vajavad tasandiprefiksit, vt eespool).

curl "https://pump.elemroot.com/Gazetter/layer/getDescription/?key=docs_382d376eaaa6d004b7b93b7d&id=3069760"

{
  "object": {
    "R_ID": 3069760,
    "AADRESS_ID": 3069760,
    "KOODAADRESS": null,
    "POSTIINDEKS": "60532",
    "E": 26.74628263,
    "N": 58.39577394,
    "AADRESS_ID_YLES": 3040077,
    "A_LOOMISE_AEG": null,
    "A_MUUTMISE_AEG": null,
    "A_STAATUS_ID": 1,
    "A_KIHT_ID": null,
    "A0_NIMI": "Eesti Vabariik",
    "A1_NIMI": "Tartu maakond",
    "A1_EHAK": "0079",
    "A2_NIMI": "Tartu linn",
    "A2_EHAK": "0793",
    "A3_NIMI": "Tartu linn",
    "A3_EHAK": "8151",
    "A4_NIMI": null,
    "A5_NIMI": "Muuseumi tee",
    "A5_NIMI_INIT": "Muuseumi tee",
    "A6_NIMI": null,
    "A7_NIMI": "2",
    "A8_NIMI": null,
    "A3_POP": null,
    "POP": 99900
  },
  "success": true
}

Olulisemad väljad:

Tundmatu ID korral tagastatakse {"success": false}.

AADRESS_ID → täisaadress (ja koos geokodeerimisega)

Geokodeerimine ise ei toeta AADRESS_ID järgi otsingut: see ID esineb seal ainult väljundis. ID järgi täisaadressi leidmiseks kasuta gazetteeri getDescription-it, mis tagastab kogu aadressikirje (komponendid + koordinaadid). Tüüpiline kasutus:

1. Sul on AADRESS_ID (nt geokodeerimise varasemast vastusest: väli AADRESS_ID / <aid>, või andmebaasist).
2. Päri täisaadress ID järgi:

   curl "https://pump.elemroot.com/Gazetter/layer/getDescription/?key=docs_382d376eaaa6d004b7b93b7d&id=3069760"

   Vastus sisaldab komponente A1_NIMI…A7_NIMI, POSTIINDEKS ja koordinaate E/N; st aadress on juba olemas (koordinaatideks geokodeerimist polegi vaja).
3. Kui tahad selle siiski geokodeerimisest läbi lasta (nt teises koordinaatsüsteemis, või et saada json2/kml väljund), koosta getDescription väljadest aadressitekst ja saada geokodeerijale. Postiindeks (POSTIINDEKS) tagab õige paiga:

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

Ülemobjektide ahel (getFillInfo)

Tagastab aadressi ülemobjektide ahela (lehest juureni). Sobib kaskaad-valikute eeltäitmiseks, kui on teada lõppaadressi AADRESS_ID.

curl "https://pump.elemroot.com/Gazetter/layer/getFillInfo/?key=docs_382d376eaaa6d004b7b93b7d&id=3069760"

{
  "addressObjects": [
    { "AADRESS_ID_YLES": 3040077, "TASE": 5, "AADRESS_ID": 3069760 },
    { "AADRESS_ID_YLES": 3020414, "TASE": 4, "AADRESS_ID": 3040077 },
    { "AADRESS_ID_YLES": 3020404, "TASE": 3, "AADRESS_ID": 3020414 },
    { "AADRESS_ID_YLES": 2822791, "TASE": 2, "AADRESS_ID": 3020404 },
    { "AADRESS_ID_YLES": 1001,    "TASE": 1, "AADRESS_ID": 2822791 }
  ],
  "success": true
}

Iga element: objekti AADRESS_ID, selle vanem AADRESS_ID_YLES ja TASE.

Kaskaad-nimekiri (currentLayer)

Listib ühe taseme aadressiobjektid (id + nimi). Kasuta rippmenüüde ehitamiseks: vali maakond, siis listi omavalitsused jne.

Tasemed (l)

Kasutatavad väärtused on 1–6:

NB: taseme number EI ole sama, mis getDescription komponendiveeru A1…A8 number; tase 4 katab nii A4 (väikekoht) kui A5 (tänav), tase 5 nii A6 (nimi) kui A7 (majanumber), tase 6 on A8 (korter). Vastuse nimi on neist täidetud variant.

Millal p, millal g?

p on tavaline kaskaad-samm: listi taseme l objektid, mille otsene vanem on p. g võimaldab ühe taseme vahele jätta: listi objektid vanavanema järgi. Praktilised kasutused:

• l=3&g=<maakond>: kõik asustusüksused terves maakonnas (üle omavalitsuste).
• l=4&g=<omavalitsus>: kõik tänavad ja väikekohad terves omavalitsuses (üle asustusüksuste; kaasa arvatud otse omavalitsuse all olevad).
• l=5&g=… erand: majade tasemel käitub g nagu p (otsene vanem); kasuta seal p-d.

curl "https://pump.elemroot.com/Gazetter/layer/currentLayer/?key=docs_382d376eaaa6d004b7b93b7d&l=1"

{
  "success": true,
  "addressList": [
    { "id": 100002,  "nimi": "Harju maakond" },
    { "id": 100003,  "nimi": "Hiiu maakond" },
    { "id": 2822791, "nimi": "Tartu maakond" },
    { "id": 100009,  "nimi": "Saare maakond" }
  ]
}

curl "https://pump.elemroot.com/Gazetter/layer/currentLayer/?key=docs_382d376eaaa6d004b7b93b7d&l=2&p=2822791"

{
  "success": true,
  "addressList": [
    { "id": 2974743, "nimi": "Elva vald" },
    { "id": 2822792, "nimi": "Kambja vald" },
    { "id": 3158291, "nimi": "Kastre vald" },
    { "id": 3302125, "nimi": "Luunja vald" }
  ]
}

curl "https://pump.elemroot.com/Gazetter/layer/currentLayer/?key=docs_382d376eaaa6d004b7b93b7d&l=4&p=3020414"

{
  "success": true,
  "addressList": [
    { "id": 3039375, "nimi": "A. H. Tammsaare tänav" },
    { "id": 3039126, "nimi": "Anne tänav" }
  ]
}

curl "https://pump.elemroot.com/Gazetter/layer/currentLayer/?key=docs_382d376eaaa6d004b7b93b7d&l=5&p=3039126"

{
  "success": true,
  "addressList": [
    { "id": 3047936, "nimi": "1" },
    { "id": 3083839, "nimi": "11" },
    { "id": 3066145, "nimi": "14a" }
  ]
}

curl "https://pump.elemroot.com/Gazetter/layer/currentLayer/?key=docs_382d376eaaa6d004b7b93b7d&l=6&p=3047936"

{
  "success": true,
  "addressList": [
    { "id": 3124193, "nimi": "1" },
    { "id": 3124202, "nimi": "10" }
  ]
}

Kui tasemel objekte pole (nt majal pole kortereid), tuleb {"success": false, "addressList": []}; kaskaadis tähendab see, et valik on lõpus.

Iga id on aadressiobjekti AADRESS_ID, mida saab kasutada järgmise taseme vanemana (p) või getDescription sisendina.

Millal mida kasutada

curl "https://pump.elemroot.com/Gazetter/layer/currentLayer/?l=4&g=2591894&key=docs_382d376eaaa6d004b7b93b7d"

JSONP

Teenus tagastab Access-Control-Allow-Origin: *; moodsas brauseris piisab tavalisest fetch()-ist. JSONP on alles vanemate klientide jaoks.

JSONP jaoks lisa callback: vastus mähitakse funktsioonikutsesse:

curl "https://pump.elemroot.com/Gazetter/layer/getDescription/?key=docs_382d376eaaa6d004b7b93b7d&id=3069760&callback=cb"

cb({"object":{ ... },"success":true})

Content-Type jääb ka JSONP puhul application/json-iks ja callback ei mõjuta serveri cache't (puhverdatakse mähkimata vastus).

Cache

Vastuseid puhverdatakse serveris 24 tundi; cache-võti on parameetrite komplekt (layer, id, l, p, g, c). Pärast andmeuuendust võib vana vastus seega kuni ööpäeva püsida: arvesta sellega, kui võrdled gazetteeri vastust sama hetke geokodeerimisvastusega.

Veakäsitlus

Gazetteer vastab sisulistele vigadele enamasti 200-ga ja {"success": false}-ga; tühi tulemus ja vigane sisend näevad ühesugused välja, seega kontrolli sisendit. HTTP-veakoodid tulevad ainult võtme, kiiruspiirangu ja liiga laia päringu korral.

Näited galeriis

• Aadressitasemed kirjutamisvõimalusega
• Tasemepõhine aadressivalik
• Aadressiotsing ja tasemepõhine aadressivalik
• Aadressivalija valmiskomponent