Integrations · Installation guide

PHP library

Postcode lookup from your server: online store, order or warehouse software, CRM. A single file without dependencies that also works on older servers.

Download the libraryv1.0.0

1 file

no dependencies

PHP 5.6–8.4

old and new servers

LT · LV · EE

addresses

Getting started

About the library

The library is for server-side lookups: when the postcode has to be determined for an order, an invoice or a shipment. For suggestions in a form while the user types, use the JavaScript library.

• Address → postcode, suggestions, structured search, addresses by postcode or coordinates.
• Addresses in Lithuania, Latvia and Estonia.
• A single exception class with clear codes.

Installation

Download the archive and add PostAPIClient.php to your project:

PHP

require 'PostAPIClient.php';

Or with Composer – the archive contains composer.json (package postapi/client):

composer.json

{
  "repositories": [{ "type": "path", "url": "lib/postapi-php-client" }],
  "require": { "postapi/client": "^1.0" }
}

Getting started

Quick start

PHP

require 'PostAPIClient.php';

$postapi = new PostAPI\Client('YOUR_API_KEY');

$result = $postapi->address('Gedimino pr. 9, Vilnius');

echo $result->postcode();          // LT-01103
echo $result->first()['city'];     // Vilnius

Search methods

MethodArgumentsDescription

address()

$text, $options

Free-text address: “Gedimino pr. 9, Vilnius”, “Kauno m. Savanorių pr. 120”.

autocomplete()

$text, $options

Suggestions for unfinished text (the user is still typing): “Savanor”, “Gedimino pr 9”.

search()

$fields, $options

Structured search by separate fields: city, street, house_number, municipality.

postcode()

$code, $options

Addresses by postcode: “LT-01103” or “01103”.

nearby()

$lat, $lon, $meters

Nearest addresses by coordinates (150–10,000 m). Records include the distance in metres (distance).

request()

$params

Any request with API parameters (see the API documentation).

PHP

$postapi->autocomplete('Savanor', ['limit' => 5]);

$postapi->search([
    'city' => 'Vilnius',
    'street' => 'Gedimino pr.',
    'house_number' => '9',
]);

$postapi->postcode('LT-01103');

$postapi->nearby(54.6855, 25.2873, 300);

$postapi->address('Brīvības iela 100, Rīga', ['country' => 'LV']);

The second argument – other API parameters: limit (1–20), page, country (LT / LV / EE), wide_number, order.

Response

Result

MethodReturnsDescription

found()

bool

Whether at least one address was found. Nothing found is not an error.

first()

array | null

The first (best matching) record.

postcode()

string | null

Postcode of the first record: “LT-01103”, with postcode(false) – “01103”.

rows()

array

All records on this page. The result can also be used in foreach.

total()

int

Total number of records found.

page(), pages()

int

Current page and number of pages.

apartment()

string | null

Apartment recognised in the address: “Laisvės pr. 44-78” → “78”.

freeTier()

bool

Free plan – a link to PostAPI.lt is required on the website.

PHP

$result = $postapi->autocomplete('Laisvės pr. 44-78');

foreach ($result as $row) {
    echo $row['address'], ', ', $row['city'], ' ', $row['postcode_full'], "\n";
}

echo $result->apartment();   // 78

Record fields: postcode_full, postcode, street, house_number, address, city, city2, municipality, lat, lon, country (+ distance for coordinate searches).

Settings

SettingDefaultDescription

country

Default country for all requests: LT, LV or EE.

timeout

Request timeout in seconds.

connectTimeout

Connection timeout in seconds (cURL).

transport

auto

auto – cURL, or file_get_contents if cURL is missing; curl or stream can be set explicitly.

apiUrl

api.postapi.lt

API URL.

PHP

$postapi = new PostAPI\Client('YOUR_API_KEY', [
    'country' => 'LV',
    'timeout' => 5,
]);

Errors

All errors are a single exception PostAPI\PostAPIException. The type – getType(), the API error code – getCode().

PHP

try {
    $result = $postapi->address($_POST['address']);
} catch (PostAPI\PostAPIException $e) {
    if ($e->getType() === 'API' && $e->getCode() === 1002) {
        // request limit exceeded
    }
    error_log($e->getMessage());
}

TypegetCode()Description

API

1001–1006

API error, getCode() – the error code: 1002 – limit exceeded, 1003 – invalid key, 1006 – unsupported country.

NETWORK

Could not connect to the API.

TIMEOUT

Timeout exceeded.

HTTP, INVALID_RESPONSE

Unexpected API response.

CONFIG

API key not set or invalid public key.

Security

Token for the JS library

If you use the JavaScript library on your website, the API key does not have to be shown on the page: your server creates a temporary token (valid for 180 minutes).

PHP – /postapi-token.php

require 'PostAPIClient.php';

header('Content-Type: application/json');
echo json_encode([
    'token' => PostAPI\Client::createToken('YOUR_API_KEY', file_get_contents('postapi-public.pem')),
]);

JavaScript

PostAPI.attach("#address", {
  tokenUrl: "/postapi-token.php",
  fields: { postcode: "#postcode" }
});

Public key for tokens – postapi-public.pem.

Technical details

Requirements

• PHP 5.6–8.4 – no warnings on new versions either.
• cURL or, if it is missing, allow_url_fopen (file_get_contents).
• OpenSSL – only for tokens for the JS library.
• Works with frameworks that turn warnings into exceptions (Laravel, Symfony and others).

With a free API key, a link to PostAPI.lt is required on the website or in the application (see the API documentation).

API documentation