InPost Geowidget

InPost GeoWidget — Integration Guide (Sandbox)

Environment: Sandbox. Assets are served from https://sandbox-global-geowidget-sdk.easypack24.net. For production use the production guide (host https://geowidget.inpost-group.com).

The GeoWidget is an embeddable map for selecting InPost pickup points (parcel lockers / POP / cool lockers). It is delivered as a custom element <inpost-geowidget> plus a CSS file, and can be embedded in any web page.

This single document contains everything needed for integration: setup, element attributes, config options, and the full programmatic API (methods and types) — no external references required.


Getting your token

To start using the GeoWidget on your website:

  1. Contact your InPost Account Manager or the Integration Team.
  2. Share your domain URL that will be correlated with a GeoWidget key.

A Merchant Portal with self-service GeoWidget key setup is in progress.

The key you receive is the PUBLIC token passed to the token attribute of <inpost-geowidget>. It is bound to the domain(s) you provided, so the widget will not load on other origins.


1. Basic integration

Add the following lines to the <head> of your page:

<link rel="stylesheet" href="https://sandbox-global-geowidget-sdk.easypack24.net/inpost-geowidget.css"/>
<script src='https://sandbox-global-geowidget-sdk.easypack24.net/inpost-geowidget.js' defer></script>
<script>
function afterPointSelected(point) { alert('Selected point: ' + point.name); }
</script>

Then embed the custom element where the map should appear:

<inpost-geowidget onpoint="afterPointSelected" token='token-for-geo' country='GB,PL' language='pl' config='parcelCollect'></inpost-geowidget>

2. Complete integration

Instead of a globally named function, you can listen for the onpointselect event:

<link rel="stylesheet" href="https://sandbox-global-geowidget-sdk.easypack24.net/inpost-geowidget.css"/>
<script src='https://sandbox-global-geowidget-sdk.easypack24.net/inpost-geowidget.js' defer></script>
<script>
document.addEventListener('onpointselect', (event) => alert(event.detail.name));
</script>
<inpost-geowidget onpoint="onpointselect" token='token-for-geo' language='pl' config='parcelCollect'></inpost-geowidget>

3. Element attributes

attribute required description
token yes The PUBLIC token (GeoWidget key) bound to your domain. See Getting your token.
config yes Defines which point functions / types are displayed on the map. See Config options.
onpoint no Name of a global function (or an event name) invoked after a point is selected on the map.
language no Default interface language. If the user has already used the widget, their previous language is used. One of: pl, en, uk, de, es, fr, it, nl, pt, cs, sk.
country no One or more comma-separated country codes from: BE, GB, ES, FR, IT, LU, NL, PL, PT, AT, HU, CZ, SK. The first value sets the default map location when geolocation is disabled on the device.

4. Config options

# Description config value Points type Statuses functions payment_available location_247 Partner id Filters for type
1 Showing pickup points for pre-paid orders parcelCollect parcel_locker Operating, NonOperating parcel_collect false false — All: parcel_locker
Parcel lockers: parcel_locker_only
Parcel point: parcel_locker_superpop
2 Presentation of collection points for pick-up orders parcelCollectPayment parcel_locker Operating, NonOperating parcel_collect true — — All: parcel_locker
Parcel lockers: parcel_locker_only
Parcel point: parcel_locker_superpop
3 Presentation of collection points for PWW orders parcelCollect247 parcel_locker Operating, NonOperating parcel_collect — true — All: parcel_locker
Parcel lockers: parcel_locker_only
Parcel point: parcel_locker_superpop
4 Presentation of senders' points parcelSend parcel_locker, pop Operating parcel_send — — — All: parcel_locker, pop
Parcel lockers: parcel_locker_only
Parcel point: pop, parcel_locker_superpop
5 Presentation of InPost pickup points for pre-paid orders parcelCollectInPost parcel_locker Operating, NonOperating parcel_collect — — 0,33,61 All: parcel_locker
Parcel lockers: parcel_locker_only
Parcel point: pop, parcel_locker_superpop
6 Presentation of InPost collection points for cash-on-delivery orders parcelCollectPaymentInPost parcel_locker Operating, NonOperating parcel_collect — — 0,33,61 All: parcel_locker
Parcel lockers: parcel_locker_only
Parcel point: pop, parcel_locker_superpop
7 Presentation of APMX (fridge modules) cooledDeposit parcel_locker Operating, NonOperating cool_parcel_collect — — — All: parcel_locker
Parcel lockers: parcel_locker_only
Parcel point: pop, parcel_locker_superpop

A dash (—) marks columns that do not apply to a given configuration.


5. Programmatic API

The generated reference for the interfaces below is available in the sidebar: ApiInterface.

Accessing the API

The API object becomes available on the inpost.geowidget.init event:

<inpost-geowidget id="geowidget" onpoint="handlePointSelection" token='myTokenHere' language='pl' config='parcelCollect'></inpost-geowidget>

<script>
const geowidget = document.getElementById('geowidget');
// Listener for the geowidget init event
geowidget.addEventListener('inpost.geowidget.init', (event) => {
// Reference to the api object
const api = event.detail.api;

// Call an api method
api.changePosition({ longitude: 20.318968, latitude: 49.731131 }, 16);
});
</script>

Methods

Method Description
search(query: string): void Run a search and show the result list.
hideSearchResult(): void Hide the search result list.
clearSearch(): void Clear the search input.
showPoint(name: string): void Show the point with the given name on the map.
showPointDetails(name: string): void Open the details panel for the point with the given name.
selectPoint(name: string): void Trigger the onpoint callback with the data of the point with the given name.
changeLanguage(lang: LanguageCode): void Change the interface language.
changePointsType(type: FilterPointsType): void Change the type of points shown on the map.
changeZoomLevel(zoom: number): void Change the map zoom level.
changePosition(position: LocationInterface, zoom?: number): void Center the map on the given position; optionally set the zoom level.
addPointSelectedCallback(callback: (point: PointInterface) => void): void Register a callback invoked after a point is selected. Multiple callbacks can be registered.

Point selection

A selected point is delivered either to the function named in the onpoint attribute, or to any callback registered with addPointSelectedCallback. The callback receives a PointInterface object (see Types).

api.addPointSelectedCallback((point) => {
console.log('Selected point:', point.name, point.address_details);
});

Escape key (modal dialogs)

The widget is rendered inside an iframe, so key presses made while focus is inside the widget do not reach the host page. If you show the widget in a modal dialog, listen for the inpost.geowidget.escape event to close the dialog with the Escape key (WCAG 2.1.2, dialog pattern).

  • The event is dispatched on the <inpost-geowidget> element and bubbles. It has no detail.
  • Escape first closes the widget's own UI (the point details panel, the language list). The event is sent only when there is nothing left to close in the widget, so the user may need to press Escape twice.
  • If you don't listen for the event, nothing changes for your integration.
<inpost-geowidget id="geowidget" token='myTokenHere' language='pl' config='parcelCollect'></inpost-geowidget>

<script>
document.getElementById('geowidget').addEventListener('inpost.geowidget.escape', () => {
// Close your modal and return focus to the element that opened it
closeGeowidgetModal();
});
</script>

6. Types

// Interface language
type LanguageCode = 'en' | 'es' | 'fr' | 'it' | 'nl' | 'pl' | 'pt' | 'uk' | 'de' | 'cs' | 'sk';

// Point type filter used by changePointsType()
type FilterPointsType = 'ALL' | 'PARCEL_LOCKER' | 'POP';

// Geographic position used by changePosition()
interface LocationInterface {
longitude: number;
latitude: number;
distance?: number;
}

// Physical point type(s)
enum PointTypeEnum {
PARCEL_LOCKER = 'parcel_locker',
POP = 'pop',
PARCEL_LOCKER_SUPERPOP = 'parcel_locker_superpop',
}

interface AddressInterface {
building_number: string;
city: string;
flat_number: string;
post_code: string;
province: string;
street: string;
}

// Delivered to onpoint / addPointSelectedCallback
interface PointInterface {
name: string;
image_url: string;
location: LocationInterface;
type: PointTypeEnum[];
address_details: AddressInterface;
address: { line1: string; line2: string };
location_247: boolean;
location_description: string;
payment_point_descr: string;
apm_doubled: string;
virtual: string;
opening_hours: string;
recommended_low_interest_box_machines_list: string[];
payment_type: { 2?: string };
partner_id: number;
physical_type_mapped?: string;
physical_type_description?: string;
easy_access_zone?: boolean;
operating_hours_extended: OpenedHoursWeek;
country: string;
}

interface OpenedHoursWeek {
customer?: { [weekday in 'monday'|'tuesday'|'wednesday'|'thursday'|'friday'|'saturday'|'sunday']: OpenedHoursRange[] };
}

interface OpenedHoursRange {
start: number;
end: number;
}

Generated using TypeDoc