Integracijos · Diegimo instrukcijos

PHP biblioteka

Pašto kodų paieška iš jūsų sistemos serverio: el. parduotuvės, užsakymų ar sandėlio programos, CRM. Vienas failas be priklausomybių, veikia ir senesniuose serveriuose.

Atsisiųsti bibliotekąv1.0.0
1 failas
be priklausomybių
PHP 5.6–8.4
seni ir nauji serveriai
LT · LV · EE
adresai
Pradžia

Apie biblioteką

Biblioteka skirta paieškai serverio pusėje: kai pašto kodą reikia nustatyti užsakymui, sąskaitai ar siuntai. Pasiūlymams formoje, kol vartotojas rašo, naudokite JavaScript biblioteką.

  • • Adresas → pašto kodas, pasiūlymai, struktūrinė paieška, adresai pagal pašto kodą ar koordinates.
  • • Lietuvos, Latvijos ir Estijos adresai.
  • • Viena klaidų klasė su aiškiais kodais.
Diegimas

Diegimas

Atsisiųskite archyvą ir įkelkite PostAPIClient.php į savo projektą:

PHP
require 'PostAPIClient.php';

Arba per Composer – archyve yra composer.json (paketas postapi/client):

composer.json
{
  "repositories": [{ "type": "path", "url": "lib/postapi-php-client" }],
  "require": { "postapi/client": "^1.0" }
}
Pradžia

Greitas startas

PHP
require 'PostAPIClient.php';

$postapi = new PostAPI\Client('JŪSŲ_API_RAKTAS');

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

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

Paieškos metodai

address()
$text, $options

Laisvo teksto adresas: „Gedimino pr. 9, Vilnius“, „Kauno m. Savanorių pr. 120“.

autocomplete()
$text, $options

Pasiūlymai nebaigtam tekstui (vartotojas dar rašo): „Savanor“, „Gedimino pr 9“.

search()
$fields, $options

Struktūrinė paieška pagal atskirus laukus: city, street, house_number, municipality.

postcode()
$code, $options

Adresai pagal pašto kodą: „LT-01103“ arba „01103“.

nearby()
$lat, $lon, $metrai

Artimiausi adresai pagal koordinates (150–10 000 m). Įrašuose – atstumas metrais (distance).

request()
$params

Bet kokia užklausa su API parametrais (žr. API dokumentaciją).

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']);
Antras argumentas – kiti API parametrai: limit (1–20), page, country (LT / LV / EE), wide_number, order.
Atsakymas

Rezultatas

found()
bool

Ar rastas bent vienas adresas. Nieko neradus – ne klaida.

first()
array | null

Pirmas (tinkamiausias) įrašas.

postcode()
string | null

Pirmo įrašo pašto kodas: „LT-01103“, su postcode(false) – „01103“.

rows()
array

Visi įrašai šiame puslapyje. Rezultatą galima naudoti ir foreach.

total()
int

Visų rastų įrašų skaičius.

page(), pages()
int

Dabartinis puslapis ir puslapių skaičius.

apartment()
string | null

Butas, atpažintas adrese: „Laisvės pr. 44-78“ → „78“.

freeTier()
bool

Nemokamas planas – svetainėje privaloma nuoroda į PostAPI.lt.

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
Įrašo laukai: postcode_full, postcode, street, house_number, address, city, city2, municipality, lat, lon, country (+ distance paieškoje pagal koordinates).
Nustatymai

Nustatymai

country
LT

Numatyta šalis visoms užklausoms: LT, LV arba EE.

timeout
10

Užklausos laiko limitas sekundėmis.

connectTimeout
5

Prisijungimo laiko limitas sekundėmis (cURL).

transport
auto

auto – cURL, o jei jo nėra – file_get_contents; galima nurodyti curl arba stream.

apiUrl
api.postapi.lt

API adresas.

PHP
$postapi = new PostAPI\Client('JŪSŲ_API_RAKTAS', [
    'country' => 'LV',
    'timeout' => 5,
]);
Klaidos

Klaidos

Visos klaidos – viena išimtis PostAPI\PostAPIException. Tipas – getType(), API klaidos kodas – getCode().

PHP
try {
    $result = $postapi->address($_POST['address']);
} catch (PostAPI\PostAPIException $e) {
    if ($e->getType() === 'API' && $e->getCode() === 1002) {
        // viršytas užklausų limitas
    }
    error_log($e->getMessage());
}
API
1001–1006

API klaida, getCode() – klaidos kodas: 1002 – viršytas limitas, 1003 – blogas raktas, 1006 – nepalaikoma šalis.

NETWORK
0

Nepavyko prisijungti prie API.

TIMEOUT
0

Viršytas laiko limitas.

HTTP, INVALID_RESPONSE
0

Netikėtas API atsakymas.

CONFIG
0

Nenurodytas API raktas ar netinkamas viešasis raktas.

Saugumas

Token'as JS bibliotekai

Jei svetainėje naudojate JavaScript biblioteką, API rakto puslapyje rodyti nereikia: jūsų serveris sukuria laikiną token'ą (galioja 180 min.).

PHP – /postapi-token.php
require 'PostAPIClient.php';

header('Content-Type: application/json');
echo json_encode([
    'token' => PostAPI\Client::createToken('JŪSŲ_API_RAKTAS', file_get_contents('postapi-public.pem')),
]);
JavaScript
PostAPI.attach("#address", {
  tokenUrl: "/postapi-token.php",
  fields: { postcode: "#postcode" }
});
Viešasis raktas token'ams – postapi-public.pem.
Techninė informacija

Reikalavimai

  • • PHP 5.6–8.4 – be įspėjimų ir naujose versijose.
  • • cURL arba, jei jo nėra, allow_url_fopen (file_get_contents).
  • • OpenSSL – tik token'ams JS bibliotekai.
  • • Veikia su framework'ais, kurie įspėjimus verčia išimtimis (Laravel, Symfony ir kt.).

Naudojant nemokamą API raktą, svetainėje ar aplikacijoje privaloma nuoroda į PostAPI.lt (žr. API dokumentaciją).

API dokumentacija