Pašto kodų ir adresų API v1.1

<script
    src="/static/postit/1.1.4/postit.min.js"
    integrity="sha384-yatA/SYw9XpqIeSXRNXhfvGTHO+tAa0LFuI3ArO4tjQrQTni9LYCgtRT+BnBlHNn"
    crossorigin="anonymous"></script>

Perėjimas iš API v1 į v1.1

API v1 išlieka prieinama esamoms integracijoms, tačiau naujoms integracijoms rekomenduojama API v1.1. Prieš pakeisdami esamos integracijos API adresą, patikrinkite atsakymus ir rezultatų rikiavimą.

Dokumentacija

API adresas: https://api.postit.lt/v1.1/

Užklausai būtinas API raktas, kuriam suteikta teisė naudoti API v1.1. Gaukite nemokamą API raktą. Jei turite klausimų, susisiekite nurodytais kontaktais.

API v1.1 OpenAPI dokumentacija (anglų k.) · OpenAPI 3.1 JSON specifikacija

Užklausos parametrai

Užklausos vykdomos tik GET metodu, o atsakymas pateikiamas JSON formatu.

Taip* – būtina pateikti term arba address.

Rikiavimo laukai ir prioritetai

Rikiavimo sąlygų tvarka yra svarbi. Sąlygos vertinamos iš kairės į dešinę: pirmoji yra svarbiausia, o kiekviena paskesnė naudojama tik tada, kai ankstesnių sąlygų reikšmės sutampa. Sukeitus laukus vietomis, rezultatų eilė gali pasikeisti.

asc rikiuoja nuo mažesnės reikšmės į didesnę, o desc – nuo didesnės į mažesnę.

Prioritetų rikiavimo pavyzdžiai:

• city_size-desc.city-asc.street-asc.number-asc – pirmiausia taiko miesto ar vietovės prioritetą bendrame Lietuvos vietovių sąraše.
• municipality_size-desc.city_size-desc.city-asc.street-asc.number-asc – pirmiausia taiko savivaldybės prioritetą, o jam sutapus – miesto ar vietovės prioritetą.

city_size automatiškai neprideda municipality_size, todėl šie du pavyzdžiai gali pateikti skirtingą rezultatų eilę. Abiem prioriteto laukams desc reiškia aukštesnį prioritetą pirmiau.

Paieška atpažįsta pašto kodą, adresą, gatvę, miestą ar vietovę, savivaldybę ir namo numerį. Didžiosios ir mažosios raidės paieškoje nesiskiria. Ieškoti galima ir lietuviškomis raidėmis, ir jų atitikmenimis be diakritinių ženklų, pvz., „Šiauliai“ arba „Siauliai“.

Grupuojant total nurodo visą rastų grupių skaičių prieš pritaikant limit. Negrupuojant jis nurodo visą rastų įrašų skaičių. Todėl total gali būti didesnis už grąžintų data elementų skaičių.

Kiti rezultatų puslapiai gaunami didinant page, nekeičiant paieškos ir rikiavimo parametrų. Pavyzdžiui, po page=1&limit=10 kita užklausa naudoja page=2&limit=10.

Grupuojant garantuojamas tik laukų, pagal kuriuos grupuojama, sutapimas. Pavyzdžiui, naudojant group=city, grąžintas pašto kodas nebūtinai tinka visam miestui.

city_size ir municipality_size galima naudoti kartu su group=city, group=street ir group=address. Prioriteto laukai keičia tik rezultatų eiliškumą – grupių sudėtis ir total skaičiavimas nesikeičia.

Užklausos pavyzdys

https://api.postit.lt/v1.1/?term=Savanorių+pr.+12,+Vilnius&limit=10&key=YOUR_API_KEY

Atsakymo laukai

Atsakymo pavyzdys

{
    "status": "success",
    "success": true,
    "message": "",
    "message_code": 0,
    "total": 1,
    "data": [
        {
            "post_code": "03116",
            "address": "Savanorių pr. 12",
            "street": "Savanorių pr.",
            "number": "12",
            "only_number": "12",
            "housing": "",
            "city": "Vilnius",
            "eldership": "Naujamiesčio sen.",
            "municipality": "Vilniaus m. sav.",
            "post": "Vilniaus 9-asis paštas"
        }
    ]
}

Klaidų kodai

Nemokamas išbandymas

Gauti nemokamą API raktą. Jis 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": []
}

Nemokamai naudojant pašto kodų duomenis per API, privaloma pateikti nuorodą ir nurodyti, kad duomenys gaunami iš Postit.lt:

<a href="https://postit.lt/" title="Pašto kodų paieška">Pašto kodų paieška</a>

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.

Esant poreikiui galima įsigyti visą Lietuvos pašto kodų ir adresų duomenų bazę.

Susisiekti nurodytais kontaktais.

Pakeitimai

2026-08-17 Užklausoje pridėtas page parametras.

2026-08-16 city_size tapo savarankišku visos Lietuvos miesto ar vietovės prioritetu ir automatiškai nebeįtraukia municipality_size prioriteto. Pirmųjų 30 miestų tvarka nustatyta pagal Valstybės duomenų agentūros paskelbtus 2021 m. gyventojų surašymo duomenis, o likusios vietovės pradinėje lentelėje rikiuojamos pagal adresų skaičių ir pavadinimą.

2026-08-14 municipality_size ir city_size pradėjo naudoti atskiras administruojamas API v1.1 prioritetų lenteles. API užklausose kryptis desc reiškia aukštesnį prioritetą pirmiau.

2026-08-08 Nauja API v1.1 versija – pakeistas paieškos variklis, pašalinti nenaudojami laukai.