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
- Adresų ir pašto kodų paieška.
- Adresų ir pašto kodų paieška nenurodant savivaldybės.
- Pašto kodo nustatymas pagal miestą ir adresą.
- Pašto kodo paieška pagal adresą ir automatinis formos laukų užpildymas (naudojama pirmoji WEB API versija).
Įskiepiai
- WordPress įskiepis, tinka WooCommerce el. parduotuvei. Parsisiųsti WordPress pašto kodų įskiepį.
- PrestaShop modulis, išmėgintas su 1.6 ir 1.7 versija. Parsisiųsti PrestaShop pašto kodų modulį.
- PrestaShop 8 modulis, išmėgintas su 8.1 versija. Parsisiųsti PrestaShop 8 adresų ir pašto kodo paieškos modulį.
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
| Parametras | Būtinas | Aprašymas |
|---|---|---|
| key | Taip | Suteiktas 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_code | Ne* | Paieška pagal pašto kodą. Ieškoma pagal tikslią frazę, pvz.: 00001 |
| post | Ne* | Paieška pagal pašto skyrių ar poskyrių, pvz.: Palangos 1 paštas |
| municipality | Ne* | Paieška pagal savivaldybę, pvz.: Pala |
| city | Ne* | Paieška pagal vietovę, pvz.: Palabaukščiai |
| address | Ne* | 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. |
| street | Ne* | Paieška pagal gatvės pavadinimą, jei nėra nurodytas address parametras, pvz.: Sausio 15 |
| number | Ne* | 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 | ||
| limit | Ne | Galimos reikšmės intervale 1-20, jei nenurodyta: 10 Pateikiamų rezultatų kiekio apribojimas. |
| page | Ne | Galimos reikšmės yra teigiami skaičiai, jei nenurodyta: 1 Pateikiamų rezultatų puslapis. Puslapių kiekis yra priklausomas nuo limit parametro |
| wide_number | Ne | Galimos 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ę. 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:
Galima rikiuoti pagal kelis paieškos parametrus, pvz.:
|
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
| Parametras | Tipas | Aprašymas |
|---|---|---|
| status | Tekstas | Užklausos įvykdymo būsena patekiama tekstine išraiška Galimos reikšmės: success, error |
| success | Loginis | Užklausos įvykdymo būsena pateikiama 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 |
| page | Objektas | Puslapiavimo duomenų objektas |
| 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ė |
| 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ą. |
| company | Tekstas | Lietuvos 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 | ||
| current | Skaičius | Rodomas puslapis |
| total | Skaičius | Puslapių 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 100 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 100 užklausų, tai siūlome:
- 10 €/mėn. - 1000 užklausų per diena
- 20 €/mėn. - neribojamas* užklausų kiekis per diena.
*Atsižvelgiant į serverio technines galimybes užklausų kiekis neturi viršyti 6 užklausų per sekunde.
Trumpiausias užsakymo laikotarpis yra 3 mėn.
🎁 Apmokant už 12 mėn. suteikiama 10% nuolaida.
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.
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.