Estijos adresų ir pašto kodų WEB API

API skirta Estijos adresų ir pašto kodų paieškai viename term lauke. Užklausos principas suderintas su Lietuvos API v1.1 ir Latvijos API.

API raktą galite gauti pasirinkę v1. Naujam v1 raktui Estijos API teisė suteikiama automatiškai.

Pavyzdžiai

Dokumentacija

WEB API adresas: https://api.postit.lt/ee/v1/

Užklausa pateikiama GET metodu, o atsakymas grąžinamas JSON formatu.

Užklausos parametrai

Parametras	Būtinas	Aprašymas
`key`	Taip	API raktas. Pasirinkus v1, naujam raktui automatiškai suteikiama Estijos API teisė.
`term`	Taip	Pašto kodas, ADR_ID, visas adresas arba viena ar kelios adreso dalys. Mažiausiai 3 simboliai.
`limit`	Ne	Rezultatų skaičius nuo 1 iki 20. Numatytoji reikšmė – 10.
`page`	Ne	Rezultatų puslapis nuo 1 iki 50. Numatytoji reikšmė – 1.
`wide_number`	Ne	Nustačius 1, namo numerio ieškoma pagal pradžią.
`group`	Ne	Grupavimas pagal county, municipality, city, address arba street.
`order`	Ne	Taškais atskirtos laukas-kryptis sąlygos, pavyzdžiui, city-asc.street-asc. Laukai: post_code, city, address, street, number, municipality ir county.

Paieška

Pašto kodo galima ieškoti formatais 91201, EE-91201 arba EE 91201. Atsakyme pašto kodas pateikiamas be šalies priešdėlio.

term ieško pagal ADR_ID, apskritį, savivaldybę, miestą ar gyvenvietę, gatvę, namo ir patalpos numerį bei visą adresą. Estiški diakritiniai ženklai gali būti pateikti arba praleisti. Suderinamumui taip pat priimami address ir q, tačiau naujoms integracijoms naudokite term.

Adreso struktūra

apskritis (county)
→ savivaldybė (municipality)
→ miestas arba gyvenvietė (city)
→ gatvė arba artimasis adresas (street)
→ namo numeris (number)

Užklausos pavyzdys

https://api.postit.lt/ee/v1/?term=Pürksi+keskus+7&limit=10&key=YOUR_API_KEY

Atsakymo parametrai

Laukas	Tipas	Aprašymas
`status`	Tekstas	Užklausos būsena: success arba error.
`success`	Loginis	Nurodo, ar užklausa įvykdyta sėkmingai.
`message`	Tekstas	Klaidos pranešimas; sėkmingame atsakyme tuščias.
`message_code`	Skaičius	Rezultato arba klaidos kodas.
`total`	Skaičius	Visas rastų rezultatų arba grupių skaičius.
`data`	Masyvas	Rezultatų masyvas.

`data` rezultatų masyvo laukai

Grupuojant rezultatus, žemesnių adreso lygių laukai, kurie neapibrėžia grupės, gali būti grąžinami kaip tuščios eilutės.

Laukas	Tipas	Aprašymas
`adr_id`	Skaičius	Oficialus Estijos ADS adreso identifikatorius.
`post_code`	Tekstas	Penkių skaitmenų pašto kodas be EE- priešdėlio.
`address`	Tekstas	Trumpasis adresas.
`address_full`	Tekstas	Visas oficialus adresas, skirtas rodyti naudotojui.
`street`	Tekstas	Gatvės arba kito artimojo adreso objekto pavadinimas.
`number`	Tekstas	Namo numeris, kai jis atskiriamas iš adreso.
`city`	Tekstas	Miestas arba gyvenvietė be tipo priesagos.
`city_full`	Tekstas	Visas miesto arba gyvenvietės pavadinimas.
`municipality`	Tekstas	Savivaldybė be tipo priesagos.
`municipality_full`	Tekstas	Visas savivaldybės pavadinimas.
`county`	Tekstas	Apskritis be maakond priesagos.
`county_full`	Tekstas	Visas apskrities pavadinimas.
`flat`	Tekstas arba null	Patalpos numeris, kai jį galima vienareikšmiškai atskirti.
`building_part`	Tekstas arba null	Pastato dalies numeris, oficialiame adrese rašomas po pasvirojo brūkšnio.
`country_code`	Tekstas	ISO šalies kodas EE.
`coordinates.latitude`	Skaičius	WGS84 (EPSG:4326) geografinė platuma.
`coordinates.longitude`	Skaičius	WGS84 (EPSG:4326) geografinė ilguma.
`coordinates.lest97_x`	Skaičius	Oficialaus adreso atskaitos taško L-EST97 X koordinatė.
`coordinates.lest97_y`	Skaičius	Oficialaus adreso atskaitos taško L-EST97 Y koordinatė.

Atsakymo pavyzdys

{
    "status": "success",
    "success": true,
    "message": "",
    "message_code": 0,
    "total": 1,
    "data": [
        {
            "adr_id": 2929584,
            "post_code": "91201",
            "address": "Pürksi keskus 7-10",
            "address_full": "Lääne maakond, Lääne-Nigula vald, Pürksi küla / Birkas, Pürksi keskus 7-10",
            "street": "Pürksi keskus",
            "number": "7",
            "city": "Pürksi / Birkas",
            "city_full": "Pürksi küla / Birkas",
            "municipality": "Lääne-Nigula",
            "municipality_full": "Lääne-Nigula vald",
            "county": "Lääne",
            "county_full": "Lääne maakond",
            "flat": "10",
            "building_part": null,
            "country_code": "EE",
            "coordinates": {
                "latitude": 58.9098377318856,
                "longitude": 23.65504836719229,
                "lest97_x": 480123.25,
                "lest97_y": 6530123.75
            }
        }
    ]
}

Klaidų kodai

Kodas	Reikšmė
`0`	Užklausa įvykdyta sėkmingai, taip pat kai rezultatų nėra.
`1001`	Paieškos tekstas nepateiktas arba yra per trumpas.
`1002`	Viršytas dienos užklausų limitas.
`1003`	API raktas netinkamas, negaliojantis arba neturi Estijos API teisės.
`1004`	API raktas nepateiktas.
`405`	Naudojamas nepalaikomas HTTP metodas.
`503`	Paieškos paslauga laikinai nepasiekiama.

Duomenų šaltinis

Naudojami Estijos žemės ir erdvinės plėtros tarnybos (Maa- ja Ruumiamet) Adresų duomenų sistemos (ADS) adresai ir pašto kodai. Oficialūs duomenys.

Nemokamas išbandymas

Gauti nemokamą API raktą pasirinkus v1. Jis taip pat suteikia bandomąją prieigą prie Estijos API ir leidžia atlikti iki 100 užklausų iš vieno IP adreso arba domeno per dieną.

Pasiekus dienos ribą, grąžinamas toks atsakymas:

{
    "status": "error",
    "success": false,
    "message": "Viršytas dienos užklausų limitas",
    "message_code": 1002,
    "total": 0,
    "data": []
}

Mokami planai

Jei reikia daugiau nei 100 užklausų, tai siūlome API planus:

4 €/mėn.* - 1000 užklausų per diena
8 €/mėn.* - neribojamas** užklausų kiekis per diena.
* - apmokant už 12 mėn.
** - Atsižvelgiant į serverio technines galimybes užklausų kiekis neturi viršyti 6 užklausų per sekunde.

Jei pasirenkamas vienas iš šių mokamų variantų, tai nuorodos talpinimas nėra būtinas.

Susisiekti nurodytais kontaktais.