Documentation

API documentation

Postcode API for Lithuania, Latvia and Estonia. Requests accept GET and POST methods, results are returned as application/json.

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

Getting started

Request URL

All requests are sent to a single URL. Search and settings parameters are passed as URL parameters (GET) or in the request body (POST). The same API is also available at https://api.postapi.lt/search.

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

Addresses are searched in Lithuania (default), Latvia and Estonia – the country is set with the country parameter.

Request parameters

Required and search parameters

Search parameters are optional once at least one of them is set. The house_number parameter can only be used together with another search parameter.

ParameterTypeDescription

keyrequired

string

API access key.

token

string

A temporary token instead of key – when the request is sent from a browser and the key must not be visible in the page source.

Valid for 180 minutes. How to create one – see the “Token” section.

country

string

Country: LT, LV or EE (case-insensitive).

If not set — LT. Any other value returns error 1006.

Search parameters

ParameterTypeDescription

city

string

City name or the beginning of it.

address

string

The address in one line: street, house number and, if known, the city (e.g. Birutės g. 8, Klaipėda; Birutės 8).

A postcode (LT-91202), an apartment number (Laisvės pr. 44-78) and (in LT) small typos are recognised.

q

string

Same as address (for compatibility with older modules). Used when address is not set.

street

string

Street name or the beginning of it.

Ignored when the address parameter is used.

house_number

string

House number.

Ignored when the address parameter is used.

Can only be used together with another search parameter.

postcode

string

Postcode or the beginning of it, without the country prefix (e.g. 91202, 912; LV 1050; EE 10119).

municipality

string

Municipality name or the beginning of it.

post_office

string

Post office name or the beginning of it.

lat, lon

number

Coordinates (WGS84). Returns the nearest addresses sorted by distance; the distance in metres is in the distance field.

Can be combined with other search parameters (e.g. street).

max_distance

integer

Maximum distance in metres for a coordinate search (150–10,000).

If not set — 500.

Search settings

ParameterTypeDescription

limit

integer / string

Number of records returned. Allowed values: 1 to 20.

If not set — 10 records are returned.

page

integer / string

Page number of the results. Allowed values: 1 to the number of pages given by page.total in the response.

If not set — page 1 is returned.

autocomplete

integer

1 – search while typing: address is treated as text typed by the user, the last word as the beginning of a word.

Used by the JavaScript library. If not set — 0.

wide_number

integer

0 – exact house number only (10 → 10, 10A), 1 – number as a prefix (1 → 1, 10, 11…). LT only.

If not set — 0.

order

string

Sort order of the results (not applied with autocomplete=1). Allowed fields: city, street, house_number, municipality, postcode.

Ascending: asc. Descending: desc.

Several fields can be combined (up to 3): order=city-asc.street-desc.

If not set — results are sorted automatically by relevance.

order=city-asc

order=city-asc.street-desc

Response

Results are returned as application/json.

Successful response example

{
  "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
  }
}

Response fields

ParameterTypeDescription

success

bool

Result of the request: true or false.

true when the request was processed, even if no matching records were found.

false when required parameters are missing, the API key is invalid, the request limit is exceeded or a system error occurred.

rows_returned

integer

Number of records returned.

Not present when success is false.

total_found

integer

Total number of records found (0 – nothing found; this is not an error).

Not present when success is false.

free_tier

bool

true – the free plan is used: a link to PostAPI.lt is required on the website (see “Requirements”).

The JavaScript library shows the link automatically.

took_time_ms

number

Request duration in milliseconds (took_time – in seconds).

address_apartment

string

Apartment number recognised in the address text (Laisvės pr. 44-78 → 78). Only with autocomplete=1.

data

array

Records found for the search parameters.

Empty when success is false.

page

array

Paging information.

Not present when success is false.

Record fields (in the data array)

ParameterTypeDescription

postcode_full

string

Postcode with the country prefix, e.g. LT-91202, LV-1001, EE-10117 (full format).

postcode

string

Postcode without the prefix (short format).

street

string

Street name.

house_number

string

House number.

address

string

Address — street name and house number.

city

string

City or settlement name.

city2

string

Settlement with its type or in genitive (e.g. Klaipėdos m.; EE Maardla küla).

municipality

string

Municipality (LV novads, EE vald).

post_office

string

Post office name (may be empty).

lat, lon

number

Address coordinates (WGS84).

distance

integer

Distance in metres from the given point. Only for lat / lon searches.

country

string

Country searched (LT, LV, EE).

Paging fields (in the page object)

ParameterTypeDescription

current

integer

Current page of the results.

total

integer

Number of result pages.

per_page

integer

Number of records per page.

Errors

Error messages

Errors are returned as application/json. On an error success is always false and the data array is empty. Check error_code in your code, not the message text.

Error response example

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

999Invalid token.The token is invalid.

1000The token has expired.The token is older than 180 minutes.

1001At least one search parameter is required.No search parameter was given.

1002Request limit exceeded.The daily limit is reached or the request package is used up.

1003The API key is invalid or expired.The API key is invalid or expired.

1004An API key is required.No API key was given.

1005Unexpected error. Please contact the system administrators.Internal error – please contact us.

1006Unsupported country. Allowed values of the country parameter: LT, LV, EE.Unsupported value of the country parameter.

Security

Token

When requests are sent from a browser, the API key is visible in the page source. A temporary token can be passed instead: your server encrypts key;unix_time with the PostAPI public RSA key (OAEP) and passes the token to the page. The token is valid for 180 minutes.

PHP

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

Public key (postapi-public.pem)

The JavaScript library gets and refreshes the token automatically, and the PHP library creates it in one line (Client::createToken).

Integration

Code examples

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);
}

For address search in a website form no code is needed – use the JavaScript library.

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

License

Requirements

With a free API key, a link to the PostAPI website must be placed on the website or in the application.

Link HTML code

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

Back to the home page Try the demo