Dokumentacija

API dokumentacija

Lietuvos, Latvijos ir Estijos pašto kodų API. Užklausos priima GET ir POST metodus, rezultatai grąžinami application/json formatu.

GETPOSThttps://api.postapi.lt/api.php

Pradžia

Užklausos nuoroda

Visos užklausos siunčiamos į vieną adresą. Paieškos ir nustatymų parametrai perduodami kaip URL parametrai (GET) arba užklausos kūne (POST). Tas pats API pasiekiamas ir adresu https://api.postapi.lt/search.

https://api.postapi.lt/api.php

Ieškoma Lietuvos (numatyta), Latvijos ir Estijos adresuose – šalis nurodoma parametru country.

Užklausos parametrai

Privalomi ir paieškos parametrai

Paieškos parametrai yra neprivalomi, jei bent vienas iš jų jau nurodytas. Parametrą house_number galima naudoti tik su kitu paieškos parametru.

ParametrasTipasAprašymas

keyprivalomas

string

API prieigos raktas.

token

string

Laikinas token'as vietoj key – kai užklausa siunčiama iš naršyklės ir raktas neturi būti matomas puslapio kode.

Galioja 180 min. Kaip sukurti – žr. skyrių „Token'as“.

country

string

Šalis: LT, LV arba EE (registras nesvarbus).

Jei parametras nenurodytas — LT. Kita reikšmė grąžina klaidą 1006.

Paieškos parametrai

ParametrasTipasAprašymas

city

string

Miesto pavadinimas arba pavadinimo pradžia.

address

string

Adresas viena eilute: gatvė, namo numeris ir, jei žinoma, gyvenvietė (pvz.: Birutės g. 8, Klaipėda; Birutės 8).

Atpažįstami pašto kodas (LT-91202), buto numeris (Laisvės pr. 44-78) ir (LT) nedidelės rašybos klaidos.

q

string

Tas pats kaip address (suderinamumui su senais moduliais). Naudojamas, jei address nenurodytas.

street

string

Gatvės pavadinimas arba pavadinimo pradžia.

Šis parametras yra ignoruojamas, jei naudojamas parametras address.

house_number

string

Namo numeris.

Šis parametras yra ignoruojamas, jei naudojamas parametras address.

Parametrą house_number galima naudoti tik su kitu paieškos parametru.

postcode

string

Pašto kodas arba jo pradžia, be šalies priešdėlio (pvz.: 91202, 912; LV 1050; EE 10119).

municipality

string

Savivaldybės pavadinimas arba pavadinimo pradžia.

post_office

string

Pašto skyriaus pavadinimas arba pavadinimo pradžia.

lat, lon

number

Koordinatės (WGS84). Grąžinami artimiausi adresai, surikiuoti pagal atstumą; atstumas metrais – lauke distance.

Galima derinti su kitais paieškos parametrais (pvz. street).

max_distance

integer

Didžiausias atstumas metrais paieškai pagal koordinates (150–10 000).

Jei parametras nenurodytas — 500.

Paieškos nustatymų parametrai

ParametrasTipasAprašymas

limit

integer / string

Gražinamų įrašų skaičius. Galimos reikšmės nuo 1 iki 20.

Jei parametras nenurodytas — grąžinama 10 įrašų.

page

integer / string

Pateikiamų rezultatų puslapio numeris. Galimos reikšmės nuo 1 iki maksimalaus puslapių skaičiaus, kurio nurodo API atsakyme esantis page.total.

Jei parametras nenurodytas — grąžinamas 1 puslapis.

autocomplete

integer

1 – paieška renkant tekstą: address laikomas vartotojo įvestu tekstu, paskutinis žodis – žodžio pradžia.

Naudoja JavaScript biblioteka. Jei parametras nenurodytas — 0.

wide_number

integer

0 – tik tikslus namo numeris (10 → 10, 10A), 1 – numeris kaip pradžia (1 → 1, 10, 11…). Tik LT.

Jei parametras nenurodytas — 0.

order

string

Rezultatų rikiavimo parametras (netaikomas su autocomplete=1). Galimi laukeliai: city, street, house_number, municipality, postcode.

Rikiavimas didėjimo tvarka: asc. Rikiavimas mažėjimo tvarka: desc.

Galimas rikiavimas pagal kelis laukelius (iki 3): order=city-asc.street-desc.

Jei parametras nenurodytas — naudojamas automatinis rezultatų rikiavimas.

order=city-asc

order=city-asc.street-desc

Atsakymas

Užklausos rezultatai

Rezultatai grąžinami application/json formatu.

Sėkmingo atsakymo pavyzdys

{
  "success": true,
  "rows_returned": 1,
  "total_found": 1,
  "free_tier": false,
  "data": [
    {
      "postcode_full": "LT-91202",
      "postcode": "91202",
      "street": "Birutės g.",
      "house_number": "8",
      "city": "Klaipėda",
      "city2": "Klaipėdos m.",
      "address": "Birutės g. 8",
      "municipality": "Klaipėdos m. sav.",
      "post_office": "",
      "lat": 55.700359,
      "lon": 21.140259,
      "country": "LT"
    }
  ],
  "took_time": 0.003,
  "took_time_ms": 3,
  "page": {
    "current": 1,
    "total": 1,
    "per_page": 10
  }
}

Rezultatų parametrai

ParametrasTipasAprašymas

success

bool

Užklausos rezultato parametras. Galimos reikšmės: true arba false.

Jei užklausa įvykdyta sėkmingai, grąžinamas rezultatas true, net jei nerasta kriterijus atitinkančių įrašų.

Rezultatas false grąžinamas dėl neužpildytų privalomų laukelių, blogo ar negaliojančio API rakto, viršyto užklausų limito ar įvykusios sisteminės klaidos.

rows_returned

integer

Grąžintų įrašų skaičius.

Jei success reikšmė yra false — šis parametras atsakyme neišvedamas.

total_found

integer

Iš viso surastų įrašų skaičius (0 – nieko nerasta; tai ne klaida).

Jei success reikšmė yra false — šis parametras atsakyme neišvedamas.

free_tier

bool

true – naudojamas nemokamas planas: svetainėje privaloma nuoroda į PostAPI.lt (žr. „Reikalavimai“).

JavaScript biblioteka nuorodą parodo automatiškai.

took_time_ms

number

Užklausos trukmė milisekundėmis (took_time – sekundėmis).

address_apartment

string

Buto numeris, atpažintas address tekste (Laisvės pr. 44-78 → 78). Tik su autocomplete=1.

data

array

Parametras, kuriame išvedami surasti įrašai pagal paieškos parametrus.

Jei success reikšmė yra false — šis parametras grąžinamas tuščias.

page

array

Masyvas, kuriame pateikiami puslapiavimo parametrai.

Jei success reikšmė yra false — šis parametras atsakyme neišvedamas.

Įrašo parametrai (data masyve)

ParametrasTipasAprašymas

postcode_full

string

Pašto kodas su šalies priešdėliu, pvz. LT-91202, LV-1001, EE-10117 (pilnas formatas).

postcode

string

Pašto kodas be priešdėlio (trumpas formatas).

street

string

Gatvės pavadinimas.

house_number

string

Namo numeris.

address

string

Adresas — gatvės pavadinimas ir namo numeris.

city

string

Gyvenvietės pavadinimas.

city2

string

Gyvenvietė su tipu arba kilmininku (pvz. Klaipėdos m.; EE Maardla küla).

municipality

string

Savivaldybės pavadinimas (LV novads, EE vald).

post_office

string

Pašto skyriaus pavadinimas (gali būti tuščias).

lat, lon

number

Adreso koordinatės (WGS84).

distance

integer

Atstumas metrais nuo nurodyto taško. Tik paieškoje pagal lat / lon.

country

string

Šalis, kurioje ieškota (LT, LV, EE).

Puslapiavimo parametrai (page masyve)

ParametrasTipasAprašymas

current

integer

Parametras, kuris nurodo pateiktą paieškos rezultatų puslapį.

total

integer

Parametras, kuris nurodo, kiek yra paieškos rezultatų puslapių.

per_page

integer

Parametras, kuris nurodo, kiek įrašų pateikiama viename puslapyje.

Klaidos

Klaidų pranešimai

Klaidos pranešimas grąžinamas application/json formatu. Klaidos atveju success reikšmė visuomet false, data masyvas — tuščias. Pranešimas (message) – anglų kalba; programoje tikrinkite error_code.

Pavyzdinis klaidos pranešimas

{
  "success": false,
  "message": "Request limit exceeded.",
  "error_code": 1002,
  "data": []
}

999Invalid token.Neteisingas token'as.

1000The token has expired.Token'as senesnis nei 180 min.

1001At least one search parameter is required.Nenurodytas nė vienas paieškos parametras.

1002Request limit exceeded.Viršytas paros limitas arba išnaudotas užklausų paketas.

1003The API key is invalid or expired.API raktas blogas arba negaliojantis.

1004An API key is required.Nenurodytas API raktas.

1005Unexpected error. Please contact the system administrators.Vidinė klaida – susisiekite su mumis.

1006Unsupported country. Allowed values of the country parameter: LT, LV, EE.Nepalaikoma parametro country reikšmė.

Saugumas

Token'as

Jei užklausos siunčiamos iš naršyklės, API raktas matomas puslapio kode. Vietoj jo galima perduoti laikiną token'ą: jūsų serveris užšifruoja tekstą raktas;unix_laikas PostAPI viešuoju RSA raktu (OAEP) ir perduoda token'ą puslapiui. Token'as galioja 180 min.

PHP

$publicKey = file_get_contents("postapi-public.pem");
openssl_public_encrypt($apiKey . ";" . time(), $encrypted, $publicKey, OPENSSL_PKCS1_OAEP_PADDING);
$token = base64_encode($encrypted);   // ?token=... vietoj ?key=...

Viešasis raktas (postapi-public.pem)

JavaScript biblioteka token'ą gauna ir atnaujina automatiškai, o PHP biblioteka jį sukuria viena eilute (Client::createToken).

Integracija

Kodo pavyzdžiai

curl

curl "https://api.postapi.lt/api.php?city=Klaipėda&address=Birutės+g.+8&key=API_KEY"

JavaScript (fetch)

const params = new URLSearchParams({
  city: "Klaipėda",
  address: "Birutės g. 8",
  key: API_KEY,
});

const response = await fetch(
  `https://api.postapi.lt/api.php?${params}`,
);
const result = await response.json();

if (result.success) {
  console.log(result.data);
}

Adresų paieškai svetainės formoje nereikia rašyti kodo – naudokite JavaScript biblioteką.

PHP (cURL)

$query = http_build_query([
  "city" => "Klaipėda",
  "address" => "Birutės g. 8",
  "key" => $apiKey,
]);

$response = file_get_contents(
  "https://api.postapi.lt/api.php?" . $query
);
$result = json_decode($response, true);

Licencija

Reikalavimai

Naudojant nemokamą API raktą, svetainėje ar aplikacijoje yra privaloma patalpinti nuorodą į PostAPI svetainę.

Nuorodos HTML kodas

<small>Pašto kodų integracija - <a href="http://postapi.lt" target="_blank">PostAPI.lt</a></small>

Grįžti į pagrindinį puslapį Išbandyti demo