InPost UK Limited GeoWidget Integration Guide Version 1.1

InPost UK Limited GeoWidget Integration Guide Version 1.1

Contents 1.0. Introduction... 3 1.0.1. Using this Document... 3 1.0.1.1. Document Purpose... 3 1.0.1.2. Intended Audience... 3 1.0.2. Background... 3 1.0.3. Overview... 3 1.0.4. Purpose of Usage... 3 1.1. Features and Functions... 4 1.1. 1. GeoWidget Elements... 4 1.1. 2. Searching a Locker Location by City or Postcode... 5 1.1. 3. Selecting a Locker Terminal... 7 1.1. 4. Route Planning Function... 9 1.2. Embedding the GeoWidget within a Webpage... 11 1.2.1. Dropdown List Only... 11 1.2.2. Dropdown List with Link to the Map... 12 1.2.3. Dropdown List with Link to the Map and Additional Form Fields... 13 1.2.4. No Dropdown Menu or Hyperlink to the Map... 14

3 1.0. Introduction 1.0.1. Using this Document 1.0.1.1. Document Purpose The purpose of this document is to describe the features and functions of the InPost GeoWidget. The different variants of the GeoWidget have also been discussed. 1.0.1.2. Intended Audience This document is intended for programmers and web administrators. A thorough knowledge of HTML and JavaScript is assumed. 1.0.2. Background In order to use the InPost service, a user is required to specify a locker location ID alongside other pertinent details e.g. the recipient s email address and mobile number. Details of locker terminal locations can be accessed through the InPost API. Also by using the appropriate API method, a user can shortlist locker terminal locations based on parameters such as name of the town/ city or a particular postcode. In some instances however, it s not possible to run server-side scripts on a web page 1. The InPost GeoWidget was developed to address such a scenario. 1.0.3. Overview The InPost 24/7 GeoWidget is a web-based auxiliary software application which allows the user to access locker terminal location details, select a particular locker terminal and export address details of the selected locker terminal for subsequent processing by another web-based application in order to aid in the process of creating a new shipment. The GeoWidget is built using HTML and JavaScript and uses AJAX to communicate directly with the InPost central system. The Google Maps API is used to display locker terminal locations on a map. By its inherent nature, this widget can be embedded within any web page with minimal effort. Once embedded, it can be accessed in any browser that supports JavaScript. Using JavaScript call-back functions the user selected location details can be passed over to a form on the host web page. This is of interest in case of online store checkout pages, wherein the customer is required to select a destination locker terminal when checking out after completing a purchase. 1.0.4. Purpose of Usage The InPost GeoWidget was designed primarily for small and medium sized online retailers interested in offering the InPost 24/7 service to their customers on their websites checkout pages. Online parcel brokers can also readily embed the widget on their check out pages, thereby offering their customers the option to use the InPost service. NB the InPost GeoWidget allows for the selection of a locker location only, which is one of the steps involved in the creation of a new shipment. 1 E.g. some SaaS E-commerce platforms do not allow users to run server scripts on their check-out pages.

1.1. Features and Functions 1.1.1. GeoWidget Elements 4 The InPost GeoWidget can be accessed in any web browser through the URL https://geowidget. inpost.co.uk. As annotated in the screenshot below, the widget contains the following elements: 1. A text input field to search for a locker location by a postcode and a drop down menu comprising a list of all locker locations. 2. A hyperlink to the route planning utility. 3. A list of all InPost locker terminal locations. 4. Location markers on the map. 5. A HTML button for selecting a locker terminal from the pop-up window. Once pressed, the selected locker terminal details are passed to a calling JavaScript function. 6. Alternative link to the route planning utility. 7. Hyperlink to view the locker location details in a new pop-up window. 8. Pressing this button opens a new window in the browser with a form to capture details for a user suggested location. 2 Figure 1: The InPost GeoWidget 2 Details of this page are out of the scope of this document.

5 1.1.2. Searching a Locker Location by City or Postcode A user can search for the nearest InPost locker terminals by entering a valid postcode in the first text input field and then pressing the Find button. Alternatively, all locker terminals within a particular city or town can be displayed by selecting the name of the town or city from the dropdown menu 3 and then pressing enter. The shortlisted locker terminals are displayed in the list that appears immediately below. Figure 2: Searching Locker Locations by Postcode 3 NB the list comprises only the cities with at least one InPost locker terminal

6 Figure 3 depicts locker terminal selection by City. Figure 3: Searching for Locker Locations by Town/City

7 1.1.3. Selecting a Locker Terminal Double clicking a locker terminal location marker on the map or a terminal name in the list of results will display a pop-up window within the map area. The name of the locker terminal, its photograph, address as well as the location description will be displayed within this pop-up window. Just beneath the last line of the location description are two hyperlinks labelled get point and details. Clicking on the former will refresh the current view with the route planner, which will be described in a separate section, displayed in the left hand pane. Clicking on the hyperlink labelled details will open another pop-up window comprising two different views of the location on the map, as depicted in figure 5. Pressing the select button within the pop-up window will return the selected locker terminal details to the calling JavaScript function. Figure 4: Selecting a Locker Terminal

Figure 5: Locker Location Details 8

9 1.1.4. Route Planning Function Once a locker has been selected and the user subsequently clicks the hyperlink labelled plan route, the widget screen is updated as shown in figure 6 below. In the left hand pane, there are three text fields corresponding to three points A, B and C, wherein A is the origin, B is the locker location and C denotes the destination point. Since the locker terminal was pre-selected, field B will be pre-populated. 6: Route Planner with the Locker Location Pre-selected as the Default Destination Once the user provides the postcodes for the originating location, the destination location and presses the search route button, the shortest driving route from the origin to destination is plotted on the map such that the selected InPost locker terminal lies on this route. It is noteworthy that the user can input the same postcode for the originating location and the destination, i.e. a round trip from an address to the locker location and back. The directions for the route are listed in the lower section of the left hand pane as depicted in figure 7.

Figure7: The GeoWidget Route Planning Function 10

11 1.2. Embedding the GeoWidget within a Webpage This section describes the integration of the InPost GeoWidget within the HTML code of webpage. 1.2.1. Dropdown List Only The most basic version of the GeoWidget comprises a dropdown list containing the IDs and addresses of all locker terminals across the country, as shown in figure 8. Figure 8: Dropdown List of All Locker Terminals The HTML code for the most basic version of the GeoWidget is provided below. The dropdown list is incorporated within a HTML form with the method attribute specified as POST so that the selected locker terminal ID is submitted as HTTP post transaction to another script as the need be. <form method= post > <script type= text/javascript src= https://geowidget.inpost.co.uk/dropdown. php?dropdown_name=machine ></script> <script type= text/javascript >inpost_machines_dropdown( machine_ id );</script> <br /> <input type= submit value= Submit > </form> Figure 9: HTML Code for Basic GeoWidget Variant

12 1.2.2. Dropdown List with Link to the Map In addition to the drop down menu a hyperlink to a map showing all locker locations can be included. Clicking the hyperlink will open the map in a new window. A user can select a locker terminal, either from the drop-down menu or from the map. Figure 10: Dropdown Menu with Link to a Map The HTML code for this variant of the GeoWidget is shown below. The dropdown list and the link to the map is incorporated within a HTML form with the method specified as POST. As soon as a user selects a locker terminal on the map, the current view of the dropdown list is updated so as to display the selected locker terminal. Once the user presses submit, the selected locker terminal ID is passed to a script for further processing. <form method= post > <script type= text/javascript src= https://geowidget.inpost.co.uk/dropdown.php?dropdown_name=machine > </script> <script type= text/javascript >inpost_machines_dropdown( machine_id );</script> <a href= # onclick= openmap(); return false; >Map</a> <br><input type= submit value= Submit > </form> Figure 11: HTML Code for the GeoWidget Variant with a Dropdown List and Hyperlink to the Map

13 1.2.3. Dropdown List with Link to the Map and Additional Form Fields On some web checkout pages, there may be a requirement for submitting the address of the user selected destination locker terminal. This can be facilitated with the use of a GeoWidget variant that allows for the possibility of filtering the selected locker terminal name (ID), street address and town/city name in separate text input fields within a HTML form, as shown in the figure below. Figure 12: Dropdown Menu with Link to a Map and Additional Data Fields <form method= post > <h5>choose delivery method</h5> <input type= radio name= method value= courier >Courier <br /> <input type= radio name= method value= parcel >Postal Parcel <br /> <input type= radio name= method value= InPost onclick= openmap(); >InPost<br /> <script type= text/javascript src= https://geowidget.inpost.co.uk/dropdown.php?field_to_update=name&field_ to_update2=address&user_function=user_function > </script> <h5>delivery address</h5> Name: <input type= text id= name name= name /> <input type= hidden id= address name= address disabled= disabled /> <br />Address: <input type= text id= street name= street /> <br />Town: <input type= text id= town name= town /> <br /><input type= submit value= Submit /> </form> Figure 13: HTML Code for Form with Dropdown Menu with Link to a Map and Additional Data Fields

14 1.2.4. No Dropdown Menu or Hyperlink to the Map There is a possibility of omitting the dropdown menu and hyperlink to the map. Instead radio buttons can be configured for each of the available delivery methods such that if a user selects the InPost delivery method, the GeoWidget map opens in a new pop-up window. Figure 14: GeoWidget Variant without the Dropdown Menu The HTML code for this variant of the GeoWidget is provided below. The radio buttons as well as the text input fields are incorporated within a HTML form with the method attribute specified as POST. Once a user selects a locker terminal on the map, the text input fields labelled Name, Street and Town are populated with the relevant values. Once the user presses the submit button, the selected locker terminal ID is passed to a script for further processing.

15 <form method= post > <h5>choose delivery method</h5> <input type= radio name= method value= courier >Courier <br /> <input type= radio name= method value= parcel >Postal Parcel <br /> <input type= radio name= method value= InPost onclick= openmap(); >InPost<br /> <script type= text/javascript src= https://geowidget.inpost.co.uk/ dropdown.php?field_to_update=name&field_to_update2=address&user_ function=user_function ></script> <h5>delivery address</h5> Name: <input type= text id= name name= name /> <input type= hidden id= address name= address disabled= disabled /> <br />Address: <input type= text id= street name= street /> <br />Town: <input type= text id= town name= town /> <br /><input type= submit value= Submit /> </form> Figure 15: HTML Code for Form with radio buttons and Additional Data Fields