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
- Pašto kodo nustatymas pagal miestą ir adresą.
- Pašto kodo paieška pagal adresą ir automatinis formos laukų užpildymas.
- Adresų ir pašto kodų paieška (API v2)
Į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 adresas: https://api.postit.lt/
Užklausa pateikiama GET metodu.
Atsakymas grąžinamas JSON formatu.
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šą, 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:
Galima rikiuoti pagal kelis paieškos parametrus, pvz.:
|
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 100 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 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 10 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
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.
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.