Location

Method: GET

REST:

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.

Sustainable delivery options
You can show customers when their parcel can be delivered sustainably. In the response of the Location API the follow sustainability codes be distinguished:

Code 02 = Sustainable option

Code 03 = Sustainable delivery + Sustainable option   

You can build in the corresponding communication message in your checkout;

Sustainably delivery;  “Duurzaam bezorgd”

Sustainable option;  “Duurzame optie” 

Sustainably delivery
PostNL delivers the parcel to your address with an electric vehicle or with a sustainable fuel vehicle.

Sustainable option
If we can deliver the package at a PostNL retail location or in a parcel machine we deliver fewer kilometers. We can also deliver multiple parcels at 1 (retail) point. This results in less CO2 emissions. In the below file you can find the visual assets which you can you use in your checkout to show the sustainability options. 

Visual assets

Please note that you can use the all-in-one Checkout API as well. This API combines the functionality of all the delivery and sustainability options.

Delivery option (request)
The following delivery option is supported:

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) for Same Day, Evening, Today or Sunday delivery. It may be possible that a retail location is open at the specified delivery time, but parcels will not be delivered for these delivery options at PostNL Locations.

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 locations in a map you can use the assets on this page. Here you can also find other useful icons.

Pickup at PostNL Location Belgium
If you deliver your parcels directly to pick up points in Belgium, some extra information is required for the Labelling API request. 

DownPartnerID: Use the data from the Location API response;  attribute RetailNetworkID.
DownPartnerLocation: Use the data from the Location API response; attribute LocationCode.