Pašto kodų ir adresų automatinio duomenų teikimo WEB API versija 2

Nemokamas pašto kodų WEB API raktas suteikiamas užsiregistravusiems vartotojams. Jei turite klausimų - kreipkitės nurodytais kontaktais.

Paskirtis

Skirta el. parduotuvėms ar sistemoms pagreitinti adreso paieškai ir įvedimui bei pašto kodo automatiniam užpildymui.

Pavyzdžiai

Įskiepiai

Dokumentacija

WEB API v2 (webservice) adresas: https://api.postit.lt/v2/

Užklausa pateikiama GET metodu.

Atsakymas grąžinamas JSON formatu (wiki JSON).

Užklausos parametrai

ParametrasBūtinasApraš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šą. Dėl nemokamo API rakto kreipkitės nurodytais kontaktais.
Paieškos parametrai
post_codeNe*Paieška pagal pašto kodą.
Ieškoma pagal tikslią frazę, pvz.: 00001
postNe*Paieška pagal pašto skyrių ar poskyrių, pvz.: Palangos 1 paštas
municipalityNe*Paieška pagal savivaldybę, pvz.: Pala
cityNe*Paieška pagal vietovę, pvz.: Palabaukščiai
addressNe*Paieška pagal adresą (gatvės pavadinimas ir namo numeris), pvz.: Basanavičiaus 2
Jei naudojamas šis paieškos parametras, tai į street ir number parametrus nebeatsižvelgiama.
streetNe*Paieška pagal gatvės pavadinimą, jei nėra nurodytas address parametras, pvz.: Sausio 15
numberNe*Paieška pagal namo numerį, jei nėra nurodytas address parametras. Ieškoma pagal tikslią frazę, nebent nurodytas wide_number, tada ieškoma abstrakčiau. Žiūrėti wide_number.
Paieškos nustatymų parametrai
limitNeGalimos reikšmės intervale 1-20, jei nenurodyta: 10
Pateikiamų rezultatų kiekio apribojimas.
pageNeGalimos reikšmės yra teigiami skaičiai, jei nenurodyta: 1
Pateikiamų rezultatų puslapis. Puslapių kiekis yra priklausomas nuo limit parametro
wide_numberNeGalimos reikšmės 0 arba 1, jei nenurodyta: 0 (funkcionalumas išjungtas)
Standartiškai užklausoje pateiktas namo numeris yra ieškomas tiksliai koks įvestas. Įjungus šį parametrą, ieškoma abstrakčiau. Pavyzdžiui ieškant pagal namo numeris 1, rezultate gali būti pateikti namai, kurių numeris prasideda simboliu 1, tai gali būti 1, 11, 1A, 1AK/B ir pan.
group Ne Galimos reikšmės: municipality, municipality_city, city, street (reikšmės atitinka paieškos parametrų pavadinimus, išskyrus municipality_city). Jei reikšmė nenurodyta - funkcionalumas yra išjungtas.
Šiuo nustatymų galima gautą rezultatų aibę sugrupuoti pagal nurodytą reikšmę. Taip manipuliuojant galima atlikti Lietuvos savivaldybių, miestų ir gatvių paiešką pagal pateiktą užklausą (adresų ir pašto kodų paieškos pavyzdys).

Jei šis parametras yra naudojamas su tuščiu, tokiu pačiu municipality arba city paieškos parametru (pvz.: group=municipality&municipality=), tai paieškos rezultate gaunamas savivaldybių sąrašas išrikiuotas pagal savivaldybės dydį*. O nurodžius konkrečią savivaldybę ir grupuojant pagal miestus (pvz.: municipality=Vilniaus+m.+sav.&group=city&city=) rikiuojama pagal miesto dydį*.

municipality_city reikšmė naudojama, kai reikia sugrupuoti miestus pagal savivaldybę.
Užklausos pavyzdys: group=municipality_city&city=. Šis grupavimo sprendimas naudojamas adresų ir pašto kodų paieškoje nenurodant savivaldybės.
Pavyzdžiui yra vietovė Antanavo k., kuri yra trijose savivaldybėse. Grupuojant pagal group=city gaunamas vienas rezultatas, o grupuojant pagal group=municipality_city - visi trys.

* Savivaldybių ir miestų (vietovių) dydis yra nustatytas pagal juose esančių objektų kiekį, jei šis eiliškumas neatitinka miestų dydžio pagal gyventojus, tai praneškite nurodydami užklausą, kuri grąžino blogus rezultatus.
Jei reikia surikiuoti ne pagal savivaldybės ar miesto dydį, o pavadinimą, tai reikia naudoti order paieškos nustatymo parametrą.
order Ne Galimos reikšmės yra paieškos parametrai: post_code, city, address, street, number, municipality, municipality_size (pagal savivaldybės dydį), post
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 - address=Sa&order=city-asc.street-desc

Ne* - parametras neprivalomas, jei jau yra nurodytas bent vienas paieškos parametras.

Visi paieškos parametrai, jei nenurodyta kitaip, prieš atliekant paiešką, yra apdorojami ir interpretuojami pagal tam tikras taisykles.

Ieškoti galima pagal vieną paieškos parametrą arba visus kartu. Jei ieškoma pagal kelis parametrus, tai parametrai užklausoje sujungiami IR principu, pvz.: city=Palanga&street=Basanavičius&number=2 interpretuojama kaip Palanga IR Basanavičius IR 2.

Užklausos pavyzdys

https://api.postit.lt/v2/?city=Vilnius&address=Savanorių+12&key=postit.lt-examplekey

Atsakymo parametrai

ParametrasTipasAprašymas
statusTekstasUžklausos įvykdymo būsena patekiama tekstine išraiška
Galimos reikšmės: success, error
successLoginisUžklausos įvykdymo būsena pateikiama logine išraiška
Galimos reikšmės: true, false
messageTekstasTekstinis klaidos pranešimas
Galimos reikšmės pateiktos žemiau esančioje klaidų kodai lentelėje.
message_codeSkaičiusKlaidos pranešimo kodas
Galimos reikšmės pateiktos žemiau esančioje klaidų kodai lentelėje.
totalSkaičiusVisas surastų rezultatų kiekis
dataMasyvasRezultatų masyvas
pageObjektasPuslapiavimo duomenų objektas
data rezultatų masyvo parametrai
post_codeTekstasPašto kodas, be "LT-" priešdėlio
addressTekstasNamo adresas, t.y. gatvės pavadinimas ir namo numeris.
streetTekstasGatvė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.
cityTekstasMiestas ar vietovė
municipalityTekstasSavivaldybė
postTekstasAptarnaujantis paštas
mailboxTekstasPaš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ą.
companyTekstasLietuvos pašto verslo klientai, taip pat Lietuvos pašto padaliniai turi savo atskirus pašto kodus. Pavyzdžiui adresas Konstitucijos pr. 21A, Vilnius turi du pašto kodus 08130 ir 03601, kuris priklauso Luminor bankui.
page puslapiavimo objekto parametrai
currentSkaičiusRodomas puslapis
totalSkaičiusPuslapių kiekis

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",
        "municipality": "Vilniaus m. sav.",
        "post": "Vilniaus 9-asis pa\u0161tas",
        "mailbox": "",
        "company": ""
    },
    "page": {
        "current": 1,
        "total": 1
    }
}

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 v2 paslauga
0 Nėra klaidos ir pranešimo
2001 Paieškai reikia paduoti bent vieną užpildytą argumentą
2002 Viršytas pašto kodų dienos užklausų limitas. Dėl šio apribojimo kreiptis tinklapyje nurodytais kontaktais.
2003 Nurodytas raktas yra blogas arba negaliojantis
2004 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ą.

Pasiekus dienos ribą, išvedamas rezultatas:

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

Pašto kodų duomenų bazės naudojimas per WEB API v2 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

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-07-17 Pridėtas grupavimas pagal municipality_city.

2019-05-16 Bandomasis Estijos pašto kodų paieškos WEB API pasiekiamas URL adresu: https://api.postit.lt/ee/?address=Weizenbergi+39&city=Tallinn&key=postit.lt-examplekey. Užklausos parametrai atitinka WEB API V2.

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

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

2018-08-12 Svarbu! API raktas padarytas privalomu parametru.

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

2018-05-31 pridėtas rikiavimas pagal company. Yra adresų, kurie turi kelis pašto kodus, pvz.: Gedimino pr. 7, Vilnius. Jei reikia, kad pirma būtų pateikiamas pašto kodas priskirtas adresui, tai reikia rikiuoti pagal company didėjimo tvarka (asc) - address=Gedimino+pr.+7&city=Vilnius&order=company-asc.

2018-05-13 nurodyti mokami planai ir į dokumentaciją įtrauktas API raktas

WEB API v1 ir WEB API v2 pagrindiniai skirtumai

API v2 versijoje užklausai suformuoti yra naudojami atskiri paieškos parametrai, kuriais galima lengviau manipuliuoti rezultatus. Be to perkeltas ir pabaigtas group bei pridėtas order paieškos nustatymas. Šių pakeitimų pagalba galima gauti tikslesnius rezultatus ir lankščiau integruoti į įvairias sistemas.