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

Paskirtis

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

Pavyzdžiai

Dokumentacija

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

Užklausa pateikiama GET metodu.

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

Pirmosios WEB API 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.

Užklausos parametrai

ParametrasBūtinasAprašymas
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, city, street (reikšmės atitinka paieškos parametrų pavadinimus). 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ą (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į*.
* 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, 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=Savanorių&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://postit.lt/data/v2/?city=Vilnius&address=Savanorių+12

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
numberTekstasNamo numeris
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 DNB 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",
        "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 dienos užklausų limitas

Apribojimai

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>