Geowidget integration

Get started

To start using Geowidget on your website:

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

Merchant Portal with a self-service geowidget key setup is in progress.

Basic integration

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

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

Then embed the element where the map should appear:

<inpost-geowidget
  token="your-geowidget-key"
  config="parcelCollect"
  onpoint="afterPointSelected"
  language="en"
  country="PL,IT"
>
</inpost-geowidget>

The custom element has no intrinsic size. Give it an explicit height in your CSS, otherwise it renders with zero height and the map looks like it failed to load:

inpost-geowidget {
  display: block;
  width: 100%;
  height: 500px;
}

Advanced integration

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

<link rel="stylesheet" href="https://geowidget.inpost-group.com/inpost-geowidget.css"/>
<script src="https://geowidget.inpost-group.com/inpost-geowidget.js" defer></script>
<script>
  document.addEventListener('onpointselect', (event) =>
    alert(event.detail.name),
  );
</script>

<inpost-geowidget
  token="your-geowidget-key"
  config="parcelCollect"
  onpoint="onpointselect"
  language="en"
  country="PL"
>
</inpost-geowidget>

Element attributes

attribute	required	description
`token`	yes	Your Geowidget key, correlated with your domain URL, generated in the InPost Merchant Portal or provided by InPost Integration Team.
`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`.
`country`	no	One or more comma-separated country codes from: `BE, GB, ES, FR, IT, LU, NL, PL, PT, AT, HU`. The first value sets the default map location when geolocation is disabled on the device.

language only sets the initial default. The widget remembers a visitor's last used language and keeps it on their next visit, so to force a language every time, call changeLanguage() after the inpost.geowidget.init event.

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.

Geowidget API

Accessing the API

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

<inpost-geowidget
  id="geowidget"
  onpoint="handlePointSelection"
  token="your-geowidget-key"
  language="en"
  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>

inpost.geowidget.init fires once per element. To change config or country at runtime, recreate the element and take the api from its new init event. Calls on the previous handle fail with a destroyed connection error.

There is no attribute for the initial map position, zoom level or search phrase. Those are reachable only through the api, which means the widget always appears at its own default location first and can be moved only after inpost.geowidget.init.

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

Types

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

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

Try it live

Adjust the config, points type, language, position and address below to see how the map reacts. These map directly to the element attributes and the API methods described above.

Using a token issued for a different domain, will result with a watermark, instead of live map tiles, and the map itself won't visibly move. search() still works and returns real results (it hits a public InPost API independent of the widget's own session), but map-session-gated calls are silently ignored by the widget until a token registered for this exact domain is used. Once you request a Geowidget key for your own domain, every control below will drive a fully live map.

Loading the map…

Pick a point on the map to see what your onpoint handler receives.