Documentation REST

Location webservice

Summary

  • 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.

Methods

The following GET methods are defined within the Location WebService:

Method

Description

GetNearestLocations

Returns locations nearest to the supplied location.

GetNearestLocations Geocode Returns the nearest locations from a given geolocation.

GetLocationsInArea

Returns locations within the supplied area.

GetLocation

Returns location information of the supplied location code.

Method

JSON Action (GET)

GetNearestLocations

https://api.postnl.nl/shipment/v2_1/locations/nearest

GetNearestLocations Geocodehttps://api.postnl.nl/shipment/v2_1/locations/nearest/geocode

GetLocationsInArea

https://api.postnl.nl/shipment/v2_1/locations/area

GetLocation

https://api.postnl.nl/shipment/v2_1/locations/lookup

Call details

Interface Version

2_1

Sandbox endpoint

https://api-sandbox.postnl.nl/shipment/v2_1/locations

Sandbox Swagger

https://api-sandbox.postnl.nl/shipment/v2_1/locations/swagger.json  

Production endpoint

https://api.postnl.nl/shipment/v2_1/locations

Production Swagger

https://api.postnl.nl/shipment/v2_1/locations/swagger.json

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. 

Versioning

API

Version

Release Date

Status

Changes compared to the previous (SOAP) versions

Schema Changes

Location

2_1

Jun 01, 2017

Supported

Different namespaces (1_1)
The operation GetBLSLocation has been removed (1_1)
The operation GetLocation has been added (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)
/ResponseLocationCode. (2_1) No schema changes

Yes

Guidelines

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:

Code

Decscription

PG

Pick up at PostNL location (in Dutch: Ophalen bij  PostNL Locatie) 

PGE

Pick up at PostNL location Express (in Dutch: Extra Vroeg Ophalen)

KEL*

Customer own location (in Dutch: Klant Eigen Locatie)

* Please ask your account manager for the possibility of using your own locations in this service.

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. 

Restrictions
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.

Best practice
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. 

Visual assets
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
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.

Location_Error_Codes

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.

Swagger UI

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)