JavaScript library

The library is made for online stores and websites where customers enter a delivery address. It uses the PostAPI.lt postcode API and works with addresses in Lithuania, Latvia and Estonia.

• • Search while typing or search with a button (“Find postcode”).
• • Fills the postcode, city, street, house number, building, apartment and municipality fields.
• • Recognises addresses typed without Lithuanian letters, with typos, with an apartment (Laisvės pr. 44-78).
• • Works with the keyboard and screen readers.

Load the library on the page with the address form (e.g. before the closing </body>):

<script src="https://api.postapi.lt/js/postapi.min.js"></script>

You can also download the file and host it with your website's static files – then change the src path.

Attach the library to the address field and list the fields to fill when an address is selected:

<input id="address" placeholder="Address">
<input id="postcode" placeholder="Postcode">
<input id="city" placeholder="City">

<script src="https://api.postapi.lt/js/postapi.min.js"></script>
<script>
  PostAPI.attach("#address", {
    key: "YOUR_API_KEY",
    fields: { postcode: "#postcode", city: "#city" }
  });
</script>

Suggestions appear while typing and can be selected with the mouse or keyboard (↑ ↓ and Enter). On selection the listed fields are filled and the onSelect function is called.

PostAPI.attach("#address", {
  key: "YOUR_API_KEY",
  fields: {
    postcode: "#postcode",
    city: "#city",
    apartment: "#flat"
  },
  onSelect: function (item) {
    console.log(item.postcode_full, item.city);
  }
});

When suggestions while typing are not needed: the user types the whole address and presses a button. If one address is found the fields are filled immediately, if several – a list is shown, if none – a message.

<input id="address" placeholder="Address">
<button id="find" type="button">Find postcode</button>
<input id="postcode">

<script>
  PostAPI.lookup("#address", {
    key: "YOUR_API_KEY",
    trigger: "#find",
    fields: { postcode: "#postcode" }
  });
</script>

If the form has several address blocks (e.g. shipping and billing), attach the library to each address field separately. Each one works on its own and fills only the fields of its block.

PostAPI.attach("#shipping_address", {
  key: "YOUR_API_KEY",
  fields: { postcode: "#shipping_postcode", city: "#shipping_city" }
});

PostAPI.attach("#invoice_address", {
  key: "YOUR_API_KEY",
  fields: { postcode: "#invoice_postcode", city: "#invoice_city" }
});

In the fields option give a field selector for each value. After filling, input and change events are fired, so PrestaShop, WooCommerce, React or Vue forms notice the change.

PostAPI.attach("#street", {
  key: "YOUR_API_KEY",
  sources: ["#house", "#city"],
  fields: { postcode: "#postcode" }
});

fields: {
  postcode: {
    target: "#zip",
    transform: function (value) { return value.replace("LT-", ""); }
  },
  city: function (value, item) { myCart.city = value; }
}

An API key written in the page is visible in its source. A temporary token is safer: your server creates it and passes it to the library, while the key stays on the server. The token is valid for 180 minutes and the library refreshes it automatically.

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

openssl_public_encrypt(POSTAPI_KEY . ";" . time(), $encrypted, POSTAPI_PUBLIC_KEY, OPENSSL_PKCS1_OAEP_PADDING);

header("Content-Type: application/json");
echo json_encode(["token" => base64_encode($encrypted)]);

With a free API key, a link to PostAPI.lt is required on the website. The library shows it automatically below the address field, so nothing else needs to be done:

The link text is in the language of the country being searched (the country option): “Pasta indeksu integrācija” in Latvia, “Postiindeksite integratsioon” in Estonia. After a country change (setCountry) the text is updated immediately.

On a paid plan the link is not shown. If the field shares a row with other fields, the link position can be changed with the attributionTarget option.

Adjust the colours and font of the suggestion list to your website with CSS variables:

.postapi-ac {
  --postapi-active: #fff3e0;     /* highlighted suggestion */
  --postapi-border: #e0e0e0;
  --postapi-radius: 4px;
  --postapi-font: 15px/1.4 Arial, sans-serif;
}

• • Browsers: all modern browsers, as well as Internet Explorer 11, iOS Safari 9+, Android 4.4+ – without additional libraries.
• • No dependencies: no jQuery or other libraries needed, size – 9 KB (gzip).
• • No conflicts: a single global name PostAPI, all styles prefixed with postapi-ac – the library does not change your website's look, and your styles do not break the suggestion list.
• • Accessibility: keyboard control, ARIA attributes, the number of results is announced to screen readers.