Alustamine

Kõik selle lehe näited töötavad kohe: kopeeri curl-käsk terminali, avalik demo-võti on juba sees. Teed läbi kolm päringut (aadress → koordinaadid, koordinaadid → aadress, teekond kahe punkti vahel) ning valid sobiva väljundvormingu ja koordinaatsüsteemi.

1. Endpointid

Igal teenusel on oma aadress:

Teenus	Mida teeb	Endpoint
Aadressiotsing (geokodeerimine)	aadressitekst → koordinaat + aadressikomponendid + aadressi ID; autotäide	`https://pump.elemroot.com/jgc_rest/geocode`
Pöördgeokodeerimine	koordinaat → lähim aadress	`https://pump.elemroot.com/rgc4/revgeocode`
Aadressivalik (gazetteer)	aadressipuu rippmenüüdeks (maakond → … → korter), ID → aadress	`https://pump.elemroot.com/Gazetter/…`
Teekonnaarvutus	teekond punktide vahel: pikkus, aeg, teejoon; sõidujuhised ja peatuste järjestus (ESRI)	`https://pump.elemroot.com/LogismeRouting/SURRouting`
Vektorkaart	MapLibre stiil + vektor-tile'd (EE/LV/LT detailselt, maailm ülevaatlikult)	`https://api.elemroot.com/styles/v1/elemroot/style.json`
Rasterkaart	valmis PNG/JPEG tile'd (XYZ, WMTS): kaart ja ortofoto, EPSG:3857 ja L-EST97	`https://pump.elemroot.com/xyz/{kiht}/{z}/{x}/{y}.png`

Vektorkaardi baas-URL on teine. Vektorkaart elab aadressil api.elemroot.com (mitte pump.elemroot.com) ja kasutab samuti key-parameetrit: vt Vektorkaart.

2. Autentimine

Kõik teenused nõuavad API-võtit: see antakse igas päringus kaasa query-parameetriga key. Ilma võtmeta või vale võtmega vastab server 403. Võtmega on serveri poolel seotud õigused: millised teenused on lubatud ja kas näiteks laiendatud andmed (xd=true) on avatud.

...&key=docs_382d376eaaa6d004b7b93b7d

Demo-võti. Näidetes kasutatav docs_… võti on avalik demo-võti proovimiseks: see roteerub regulaarselt (näited siin lehel kannavad alati kehtivat) ja on kiiruspiiranguga; liiga tihedad päringud saavad 429. Oma rakenduse jaoks küsi personaalne võti.

Kõik teenused tagastavad päise Access-Control-Allow-Origin: * (ka veavastustel); brauseris saab kasutada tavalist fetch()-i mis tahes lehelt. Vanemate klientide jaoks toetavad geoteenused ka JSONP-d (callback).

3. Kolm päringut: aadress → koordinaat → aadress → teekond

1) Geokodeeri aadress Muuseumi tee 2 Eesti aadressiandmestiku (ee_aid) vastu:

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

Kolm parameetrit on kohustuslikud:

Parameeter	Tähendus
`q` kohustuslik	Geokodeeritav aadress.
`gl` kohustuslik	Andmekogumi ID, nt `ee_aid`.
`key` kohustuslik	API-võti. Ilma selleta `403`.

Kui vajad aadressi komponente eraldi väljadena (maakond, tänav, majanumber, sihtnumber, aadressi ID), lisa output=json2. Vaikimisi json annab ainult aadressiteksti, koordinaadid ja täpsustaseme.

Vastuses on point.coordinates: [26.74628263, 58.39577394]: pikkus, laius.

2) Pöördgeokodeeri sama punkt tagasi aadressiks (NB sisend on lat,lon):

curl "https://pump.elemroot.com/rgc4/revgeocode?q=58.39577394,26.74628263&gl=ee_lt_lv&output=json&s=ADDRESS&key=docs_382d376eaaa6d004b7b93b7d"

Vastus: "address":"EE, Tartu maakond, Tartu linn, Tartu linn, Muuseumi tee 2", distance meetrites (siin ≈0).

3) Arvuta teekond Muuseumi tee 2-lt Raekoja platsile (sisend E,N = lon,lat; vaikimisi ainult kokkuvõte):

curl "https://pump.elemroot.com/LogismeRouting/SURRouting?pref=Fastest&start=26.74628263,58.39577394&end=26.72210014,58.37978616&output=json&key=docs_382d376eaaa6d004b7b93b7d"

Vastus: TotalDistance ≈ 3 844 m, TotalTime ≈ 8 min; teejoone saad noRouteGeom=false-ga.

Kaart lehele. Vektorkaardi kiirstart on 15 rida HTML-i valmis stiiliga: vt vektorkaardi juhendit; rastertile'd Leafleti/OpenLayersiga vt rasterkaardi juhendit. Töötavad näited koos koodiga: examples.elemroot.com.

4. Väljundvorming

Vormingu valid parameetriga output (vaikimisi json):

`output`	Sisu
`json`	Hierarhiline aadress (xAL-puu): vaikimisi
`json2`	Lameda struktuuriga aadress (`AddressLines`)
`xml` / `xml2`	Samad kaks struktuuri XML-ina
`kml`	Google Earth KML
`ads_liik_staatus`	Aadressiväljad eestikeelsete nimedega (ainult Eesti andmestik)

Andmestiku-sõltuvus. Andmekogu ee_aid puhul annab json aadressikomponendid vaid Accuracy väljana; täielikud komponendid (tänav, EHAK, sihtnumber jne) tulevad json2 väljundist. Vt juhendit.

5. Koordinaatsüsteem

Vaikimisi EPSG:4326 (WGS84, kraadid). Eesti tasapinnaliseks süsteemiks (meetrites) kasuta srs=EPSG:3301 (L-EST97):

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

Koordinaadid tagastatakse alati järjekorras [E, N]: esimene arv on idasuund, teine põhjasuund. Kraadides (EPSG:4326) tähendab see [pikkus, laius]. EPSG:3301 (L-EST97, meetrites) puhul on sama järjekord Eesti tähistuses [Y, X]: esimene arv on Y (ida), teine X (põhi); Eesti mõõtesüsteemis on X-telg põhjasuunas, seega suurem X tähendab põhjapoolsemat punkti.

Edasi: iga teenuse juhend

Igal teenusel on sama ülesehitus: ülevaade (1 näide) → juhend (parameetrid, „millal mida kasutada”, lõksud, veakäsitlus) → API viide (Swagger UI + OpenAPI YAML).

Aadressiotsing → Autotäide, hulgipäring, aadressi ID, laiendatud andmed, JSONP. Pöördgeokodeerimine → Punktist aadress, komponendid, _reverse, koordinaatide lõksud. Aadressivalik → Rippmenüü-kaskaad, ID → aadress, ülemobjektid, Eesti/Läti/Leedu. Teekonnaarvutus → Teejoon, vahepunktid, L-EST97, ESRI-liides, sõidujuhised, peatuste optimeerimine. Vektorkaart → MapLibre kiirstart, oma stiil TileJSON-ist, fondid, QGIS. Rasterkaart → XYZ ja WMTS, ortofoto, EPSG:3301 ruudustik, Leaflet/OpenLayers/QGIS. Aadressivalija (valmiskomponent) → Otsing, tasemed ja kaart oma lehele ühe skriptiga. Näidete galerii – examples.elemroot.com ↗ Kopeeritav kood iga teenuse kohta, töötab avalike URL-idega.