X-GIS JSON aadressiotsingu teenuse kirjeldus

 

NB!

Siin kirjeldatud teenus on veel küll olemas, kuid edaspidises arenduses palume aadressiotsingu funktsionaalsuse üles ehitada In-ADS komponendile.

In-ADS komponent on kirjeldatud siin.

 

See teenus tagastab tekstilise aadressi alusel aadressiobjektide infot. Tegemist on süsteemide arendajatele suunatud teenusega, mida tavakasutajal tarvis ei lähe (tavakasutajale on sama teenus kättesaadav XGIS rakendustes Otsi aadressi/tunnust otsingukasti abil).

Teenuse kasutamiseks tuleb GET päringuga pöörduda URLi http://xgis.maaamet.ee/xGIS/XGis poole. Päringu vastus tagastatakse JSON kujul, selles on leitud aadressiobjektide normaliseeritud täisaadress, tunnus ning viitepunkti askoht.

 

Parameetrid:

dogis_link

Teenus, mille poole pöördutakse. Antud teenuse nimi on getgazetteer (kohustuslik parameeter).

address

Aadress, mida otsitakse (kohustuslik parameeter).

features

Gazetteer nähtus või nende loetelu komadega eraldatuna. Määrab, milliste objektide hulgast otsitakse. (kohustuslik parameeter)

results

Tagastatav maksimum tulemuste arv. Vaikeväärtuseks on 10, maksimumväärtuseks 100.

 

Parameetri features väärtusteks võivad olla:

EHAK

Otsitakse Eesti haldus- ja asustusjaotuse klassifikaatori objektide hulgast
(maakonnad, omavalitsused, asustusüksused).

VAIKEKOHT Otsitakse väikekohtade seast.
TANAV Otsitakse tänavanimede (ADS liikluspindade nimede) hulgast.
KATASTRIYKSUS Otsitakse katastriüksute hulgast.
EHITISHOONE Otsitakse hoonete seast.

 

Vastuse vorming:

Päringu vastus on esitatud UTF-8 kodeeringus.

JSON kujul vastuse esimene element on boundedBy, mis näitab vastuses olevate aadressiobjektide ruumilist ulatust (kuigi tagastatakse vaid aadresspunkti koordinaadid on ulatus leitud aadressiobjektide tegeliku ulatuse alusel). Antud element sisaldab BBOX objekti elementidega coordinates (ulatust määrava ristküliku koordinaadid) ja @srsName (koordinaatsüsteem, milles koordinaadid on esitatud).

Teine element on featureMember, mis on massiivi tüüpi ja sisaldab leitud aadressobjekte. NB! Kui vastuses on vaid üks aadressiobjekt, siis ei ole featureMember massiiv, vaid objekt, mis sisaldab üht aadressiobjekti.

Iga leitud aadressobjekt on esitatud JSON objektina, mille nimeks on tema nähtuse nimi ja koosneb elementidest PikkAadress (leitud aadress), Tunnus (tunnuse väärtus) ja ReferencePoint (Koosneb Point elemendist, mis sisaldab coordinates elementi leitud aadressobjekti tsentroidi koordinaatidega).

Kui otsitud aadresse ei leitud, tagastatakse tühi vastus.

 

Näidispäringud:

1. Otsitav aadress on Sirbi 5, tulemuste arv 5 ning otsitakse nähtuste hulgast: ehak, väikekoht, tänav, liikluspind, katastriüksus ja hooned.

http://xgis.maaamet.ee/xGIS/XGis?dogis_link=getgazetteer&address=Sirbi%205&features=EHAK,VAIKEKOHT,TANAV,KATASTRIYKSUS,EHITISHOONE&results=5

2. Otsitav aadress on Tihase 15, tulemuste arv määramata (vaikimisi 10), ning otsitakse nähtuste hulgast: katastriüksus ja hooned.

http://xgis.maaamet.ee/xGIS/XGis?dogis_link=getgazetteer&address=Tihase%2015&features=KATASTRIYKSUS,EHITISHOONE

3. Otsitav aadress on Mustamäe tee 50, tulemuste arv 20 ning otsitakse ainult hoonete hulgast.

http://xgis.maaamet.ee/xGIS/XGis?dogis_link=getgazetteer&address=Mustam%E4e%20tee%2050&features=EHITISHOONE&results=20

 

Näidisvastus:

Vastus esimesele näitepäringule. Loetavuse parandamiseks on lisatud reavahetused.

{
    "boundedBy":{
        "Box":{
            "@srsName":"EPSG:3301",
            "coordinates":"538527,6471338 659530,6590842"
        }
    },
    "featureMember":[{
        "EHITISHOONE":{
            "PikkAadress":"Harju maakond, Tallinn, Põhja-Tallinna linnaosa, Sirbi tn 5",
            "Tunnus":"101034263",
            "ReferencePoint":{
                "Point":{
                    "coordinates":"538568,6590817"
                }
            }
        }
    },
    {
        "EHITISHOONE":{
            "PikkAadress":"Tartu maakond, Tartu linn, Sirbi kaar 5",
            "Tunnus":"104017473",
            "ReferencePoint":{
                "Point":{
                    "coordinates":"659523,6471486"
                }
            }
        }
    },
    {
        "EHITISHOONE":{
            "PikkAadress":"Tartu maakond, Tartu linn, Sirbi tn 5",
            "Tunnus":"104041379",
            "ReferencePoint":{
                "Point":{
                    "coordinates":"659500,6471348"
                }
            }
        }
    },
    {
        "EHITISHOONE":{
            "PikkAadress":"Harju maakond, Tallinn, Põhja-Tallinna linnaosa, Sirbi tn 5a",
            "Tunnus":"101032246",
            "ReferencePoint":{
                "Point":{
                    "coordinates":"538570,6590811"
                }
            }
        }
    },
    {
        "KATASTRIYKSUS":{
            "PikkAadress":"Harju maakond, Tallinn, Põhja-Tallinna linnaosa, Sirbi tn 5",
            "Tunnus":"78408:808:0270",
            "ReferencePoint":{
                "Point":{
                    "coordinates":"538551,6590813"
                }
            }
        }
    }]
}