Pašto kodų WEB API

Automatinis pašto kodų ir adresų duomenų teikimas WEB API v2.

Svarbu! Nuo 2018-08-12 API raktas tapo privalomu.
Nemokamas API raktas suteikiamas užsiregistravusiems vartotojams. Jei turite klausimų - kreipkitės nurodytais kontaktais.

Pavyzdžiai

Įskiepiai

Dokumentacija

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

Užklausa pateikiama GET metodu.

Atsakymas grąžinamas JSON formatu.

Užklausos parametrai

Parametras Būtinas Aprašymas
keyTaipSuteiktas API raktas. API raktas susiejamas su IP adresu arba tinklapio domenu.
Tinklapiai ir IP adresai, kurie iki 2018-08-12 naudojo WEB API, buvo automatiškai įtraukti į sąrašą, ir pereinamuoju laikotarpiu iki 2018-12-31 galės vykdyti užklausas be rakto. Dėl nemokamo API rakto kreipkitės nurodytais kontaktais.
term Taip Užklausa, pagal kurią ieškomi pašto kodai. Užklausą turi sudaryti 3 ar daugiau simbolių. Tarpai esantys priekyje ir pabaigoje yra pašalinami.
address Taip* term parametro alternatyva. Šis parametras yra privalomas ir tikrinamas, tik tada kai nėra pateikiamas term.
limit Ne Pateikiamų rezultatų kiekio apribojimas.
Galimos reikšmės intervale 1-20, jei nenurodyta: 10
wide_number Ne Standartiškai užklausoje pateiktas namo numeris yra ieškomas tiksliai koks įvestas. Įjungus šį parametrą, ieškoma abstrakčiau. T.y. ieškant pagal namo numeris 1, rezultate gali būti pateikti namai, kurių numeris yra 1, 11, 1A, 1AK/B ir pan.
Galimos reikšmės 0 arba 1, jei nenurodyta: 0
group Ne Eksperimentinis parametras.
Leidžia gautą rezultatų aibę sugrupuoti pagal nurodytą reikšmę. Manipuliuojant šiuo parametru galima atlikti Lietuvos miestų ir gatvių paiešką pagal pateiktą užklausą.
Galimos reikšmės: city, address, street. Jei nenurodyta - šis funkcionalumas nenaudojamas
order Ne Galimos reikšmės yra paieškos parametrai: post_code, city, address, street, number, eldership, municipality, municipality_size (pagal savivaldybės dydį, asc - didžiausia viršuje)
Galima rikiavimo tvarka:
  • asc – didėjimo
  • desc – mažėjimo
Jei nenurodyta - naudojamas automatinis rezultatų rikiavimas.
Galima rikiuoti pagal kelis paieškos parametrus, pvz.:
  • pagal vieną parametrą - address=Sa&order=city-asc
  • pagal kelis parametrus - municipality_size-asc.city-asc.street-asc.number-asc
Naudojant rikiavimo parametrą, automatinis rikiavimas išjungiamas.

Užklausos pavyzdys

https://api.postit.lt/?term=Savanorių+12,+Vilnius&key=postit.lt-examplekey

Atsakymo parametrai

Parametras Tipas Aprašymas
status Tekstas Užklausos įvykdymo būsena (statusas) tekstine išraiška
Galimos reikšmės: success, error
success Loginis Užklausos įvykdymo būsena (statusas) logine išraiška
Galimos reikšmės: true, false
message Tekstas Tekstinis klaidos pranešimas
Galimos reikšmės pateiktos žemiau esančioje klaidų kodai lentelėje
message_code Skaičius Klaidos pranešimo kodas
Galimos reikšmės pateiktos žemiau esančioje klaidų kodai lentelėje
total Skaičius Visas surastų rezultatų kiekis
data Masyvas Rezultatų masyvas
data rezultatų masyvo parametrai
post_code Tekstas Pašto kodas, be "LT-" priešdėlio
address Tekstas Namo adresas, t.y. gatvės pavadinimas ir namo numeris.
street Tekstas Gatvės pavadinimas
number Tekstas Pastato/namo ir, jei yra, korpuso numeris.
Korpuso numeris atskiriamas raide "K", pvz.: 15BKC
only_number Tekstas Tik pastato numeris be korpuspo dalies, pvz.: 15B.
housing Tekstas Korpuspo numeris, pvz.: C.
city Tekstas Miestas ar vietovė
eldership Tekstas Seniūnija. Lietuvos administracinis-teritorinis vienetas.
municipality Tekstas Savivaldybė
post Tekstas Aptarnaujantis paštas
mailbox Tekstas Pašto dėžutės, kuri yra Lietuvos pašto pastate, numeris.
Reikia atkreipti dėmesį, kad prie pašto dežutės nėra pateikiami adreso duomenys. Jei ieškoma pagal adresą, tai jokios įtakos neturės. Tačiau ieškant pagal pašto kodą, pvz.: "29002", ar dėžutės numerį "pašto dėžutė 1" reikia suformuoti atskirą rezultatų išvedimo logiką.

Atsakymo pavyzdys

{
    "status": "success",
    "success": true,
    "message": "",
    "message_code": 0,
    "total": 1,
    "data": {
        "post_code": "03116",
        "address": "Savanori\u0173 pr. 12",
        "street": "Savanori\u0173 pr.",
        "number": "12",
        "only_number": "12",
        "housing": "",
        "city": "Vilnius",
        "eldership": "",
        "municipality": "Vilniaus m. sav.",
        "post": "Vilniaus 9-asis pa\u0161tas",
        "mailbox": ""
    }
}

Klaidų kodai

Žinutės kodas Žinutės tekstas
Klaidos susijusios su serveriu arba tinklapiu
404 Pagal pateiktą užklausą nepavyko nieko rasti
Šis pranešimas pateikiamas, kai nurodytas blogas WEB API adresas
503 Dėl didelio apkrovimo paslauga laikinai neprieinama
Klaidos susijusios su API paslauga
0 Nėra klaidos ir pranešimo
1001 Paieškoje įrašykite daugiau nei 2 simbolius
1002 Viršytas pašto kodų dienos užklausų limitas. Dėl šio apribojimo kreiptis tinklapyje nurodytais kontaktais.
1003 Nurodytas raktas yra blogas arba negaliojantis
1004 Privaloma nurodyti pašto kodų API raktą. Dėl šio apribojimo kreiptis tinklapyje nurodytais kontaktais.

Nemokamas išbandymas

Nemokamas API raktas leidžia atlikti iki 200 užklausų iš vieno IP adreso arba domeno per dieną. Dėl nemokamo API rakto kreiptis nurodytais kontaktais.

Pasiekus dienos ribą, išvedamas rezultatas:

{
    "status": "error",
    "success": false,
    "message": "Vir\u0161ytas dienos u\u017eklaus\u0173 limitas",
    "message_code": 1002,
    "total": 0,
    "data": []
}

Pašto kodų duomenų bazės naudojimas per WEB API yra nemokamas, todėl privaloma nurodyti (įdėti nuorodą), kad pašto kodai gaunami naudojant 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 200 užklausų, tai siūlome:

Trumpiausias užsakymo laikotarpis yra 3 mėn.

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

2024-03-11 Pridėtas rezultatų rikiavimo funkcionalumas.

2023-07-21 Prie grąžinamų duomenų masyvo pridėtas eldership parametras, kuriame pateikiamas seniūnijos pavadinimas. Seniūnija - Lietuvos, o ne miesto, administracinis-teritorinis vienetas.

2021-04-25 Prie grąžinamų duomenų masyvo pridėti only_number ir housing parametrai, kurie atskiria pastato ir korpuso numerius.
Be to API nebegrąžina mailbox duomenų.

2020-10-19 Duomenys sutikrinami ir atnaujinami naudojant duomenų šaltinį: „© Lietuvos Respublikos adresų registras“.

2019-04-11 WEB API pasiekiamas nauju URL adresu: https://api.postit.lt/. Senasis adresas išlieka.

2019-02-11 Nemokamų užklausų kiekis padidintas iki 200.

2018-08-12 API raktas padarytas privalomu parametru.

2018-08-09 paruoštas įskiepis Lietuvos pašto kodų ir adresų paieškos integracijai į WordPress sistemą

2018-03-15 pakeistas užklausų kiekis iš vieno IP adreso arba domeno per dieną

2016-08-21 įvairūs API pakeitimai

Užklausoje pridėtas limit parametras. Rezultatuose papildomai pridėti success ir message_code parametrai, be to message parametre klaidos pranešimai pateikiami lietuvių kalba. O duomenų masyve papildomai pateikiami street ir number parametrai.

2014-06-22 praplėsta pašto kodų paieška

Paieška pagal *pašto dėžutės numerį, kuris, jei yra, pateikiamas duomenų masyve.

Ieškoti pagal pašto dėžutės numerį galima panašia užklausa Pašto dėžutė 1, galima susiaurinti rezultatus nurodant miestą prie pašto dėžutės Pašto dėžutė 1 Druskininkai.

* Pastaba: Sąvoka "pašto dėžutė" - tai Lietuvos Pašte esanti ir LP išnuomojama talpykla. Tai ne ta pašto dėžutė, kuri yra Jūsų laiptinėje ar prie Jūsų namo.