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

---

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