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

Svarbu! Nuo 2018-08-12 API raktas tapo privalomu. API raktą galite nemokamai gauti parašę 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://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
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.
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, company
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&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
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 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",
        "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
2003 Nurodytas raktas yra blogas arba negaliojantis
2004 Privaloma nurodyti API raktą. Dėl nemokamo API rakto kreiptis el. paštu

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": 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:

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

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-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