- Name: Location Webservice
- Reason to Call: Retrieve a list of pick up points that support the option for direct delivery to a standard or early morning pick up point.
- Input: Address, city and country code of the preferred location Or longitude and latitude.
- Output: Locations nearest to the supplied address, location within the supplied area or location information of the location code.
The following GET methods are defined within the Location WebService:
Returns locations nearest to the supplied location.
|GetNearestLocations Geocode||Returns the nearest locations from a given geolocation.|
Returns locations within the supplied area.
Returns location information of the supplied location code.
JSON Action (GET)
If you already use the former SOAP API’s and/or you want to make use of the REST API’s, you can fill in the Request for API key form or contact your PostNL account manager to arrange this.
Changes compared to the previous (SOAP) versions
Jun 01, 2017
Different namespaces (1_1)
The Location Type has been extended with international address properties. (1_1)
Sunday sorting and options added (1_2)
Partner name and retail formula name added (1_2)
Warning added (1_2)
The Location Type has been extended with PartnerLocationCodes (1_2)
Difference between the methods.
You can use the GetNearestLocation method if you want to show the nearest pick up points for the consumer based on their postal code or specific latitude/longitude coordinates combination. If you want to show a map with the nearest pick up points, then you can use the GetLocationInArea method. This provides you an overview of the nearest pick up points.
GetLocation can be used if you know the LocationCode. This method provides you with the information of the retailer. You can find the location code in the response of the GetNearestLocations and GetLocationsInArea. The RetailNetworkID is PNPNL-01, this code can be used for all Dutch locations.
Google Maps / GetLocationsInArea
If you want to show the pick up points through Google Maps, you will need to apply an API key of Google Maps. You can get find more information at the following site: https://developers.google.com/maps/.
The GetLocationsInArea method retrieves all locations in a specific area. When a map is displayed with Google Maps, a so-called "bounding box" of the given area can be requested. The Google Maps API then returns them in NorthWest/SouthEast (NW/SE) form that you can use to retrieve the locations.
Please note that the GetLocationsInArea method accepts the coordinates in NorthWest / Southeast (NW / SE) form. This can be converted as follows:
Use the latitude of North East (NE) and the longitude of Southwest (SW) that Google Maps API returns as NorthWest (NW) value for the GetLocationsInArea call.
Use the latitude of Southwest (SW) and the longitude of North East (NE) that the Google Maps API returns as SouthEast (SE) value for the GetLocationsInArea call.
Delivery options (request)
The following delivery options are supported:
Pick up at PostNL location (in Dutch: Ophalen bij PostNL Locatie)
Pick up at PostNL location Express (in Dutch: Extra Vroeg Ophalen)
Customer own location (in Dutch: Klant Eigen Locatie)
Please make sure you only use the delivery option(s) in your contract. Also be aware you will have to use different product codes for each individual delivery option and some options/products require extra information in your confirming message, like a mobile phone number or email address. If you don’t use the right product code or if you don’t provide the correct information; the parcel cannot be delivered.
Delivery options (response)
The delivery options UL, PU and DO can be shown in the response. Please ignore these codes. These codes are internal PostNL codes.
It is not possible to offer the opportunity PG (Pick up at PostNL location) on a Sunday. So it may be possible that a location is open on Sunday, but parcels will not be delivered on Sundays at PostNL locations.
Also the combination Monday delivery and PGE (Pick up at PostNL location Express) is not possible, because the parcels will not be delivered before Monday morning 08:30 am.
Integrate all three PostNL frontend webservices into your checkout and empower your customers to choose the delivery option that suits them best.
First use the Deliverydate webservice (Get deliverydate method) to determine the available and possible delivery date(s), based on your shipping date. Use the received date from this service as a starting point in the Timeframe webservice to show customers the possible day and time of arrival. In this way you avoid showing not possible deliverydates. The postal code that customers enter by placing their order, determine the timeframes that apply to their address.
Use the Location webservice to show the nearest pickup point(s) based on the postal code or coordinates of the customers. The location(s) can be shown in a map if you want to make it visually more appealing.
The (below) visual assets can be useful to create a delivery options frame in your checkout.
To show pins of PostNL loations in a map you can use the assets on this page. Here you can also find other usefull icons.
Error codes have been specified in the below PDF file. Errors from the backend services will be caught and returned as standard API errors according to the generic error handling procedures in the API.
Request and Response codes
For explanation of the request and response codes, you can take a look at the Documentation page of this API. Here you can find all information about the attributes of the json call, like descriptions, formats and examples.
Test the RESTful API's with JSON content type format with the below Swagger tooling. To easily test the API: Click at 'Default' and/or 'Expand Operations', fill in at least the requirerd parameters and click at the 'Try it Out!' button. You can find the response code under Response Messages.
You can also test this API's by using the following Swagger url: http://petstore.swagger.io/ (expand the url with /swagger.json and click Explore)