Location

Documentation

By using the Location API you can show the nearest PostNL Pick up points based on the postal code or coordinates of the customers. This delivery option gives customers the option to pick up their parcels themselves. With more than 4000 (retail) points throughout the Netherlands and 800 points in Belgium, there is always one nearby.

Development

All the necessary information for implementing this API.
 
                                         .

Go to Technical documentation https://docs.api.postnl.nl

Why use the Location API

Up to date pick up locations
Retrieve a list of pick up points that support the option for direct delivery to a PostNL pick up point.
 
Customer convenience
You can show the nearest PostNL Pick up points based on the postal code or coordinates of the customers. If desired you can show the locations in a map for customer convenience.
 
Different methods to retrieve locations
This API contains three methods; returns locations nearest to the given address, within the supplied area or provide location information of the supplied location code.

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

Code

Decscription

PG

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

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.

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

Code examples

Request GetNearestLocation:

curl --location --request GET 'https://api-sandbox.postnl.nl/shipment/v2_1/locations/
nearest?PostalCode=3532VC&HouseNumber=49&DeliveryOptions=PG&
CountryCode=NL&DeliveryDate=02-09-2022&OpeningTime=12:30:00' \
--header 'apikey: ***' \

Response (TRUNCATED): 

{
    "GetLocationsResult": {
        "ResponseLocation": [
            {
                "Address": {
                    "City": "Bunnik",
                    "Countrycode": "NL",
                    "HouseNr": 20,
                    "HouseNrExt": "-26",
                    "Street": "van Hardenbroeklaan",
                    "Zipcode": "3981EP",
                    "Remark": "Dit is een Postkantoor. Post en pakketten die je op 
werkdagen vóór de lichtingstijd afgeeft, bezorgen we binnen Nederland de 
volgende dag. Op zaterdag worden alléén pakketten die je afgeeft voor
15:00 uur maandag bezorgd."
                },
                "DeliveryOptions": {
                    "string": [
                        "RETA",
                        "DO",
                        "PG",
                        "BW",
                        "BWUL",
                        "RT"
                    ]
                },
                "Distance": 1382,
                "Latitude": 52.06781104,
                "Longitude": 5.20001936,
                "LocationCode": 161616,
                "Name": "Boekhandel van Ravenswaaij",
                "PartnerName": "PostNL",
                "RetailNetworkID": "PNPNL-01",
                "OpeningHours": {
                    "Monday": {
                        "string": "09:00-18:00"
                    },
                    "Tuesday": {
                        "string": "09:00-18:00"
                    },
                    "Wednesday": {
                        "string": "09:00-18:00"
                    },
                    "Thursday": {
                        "string": "09:00-18:00"
                    },
                    "Friday": {
                        "string": "09:00-18:00"
                    },
                    "Saturday": {
                        "string": "09:00-17:00"
                    }
                }
            },
            {
                "Address": {
                    "City": "Bunnik",
                    "Countrycode": "NL",
                    "HouseNr": 20,
                    "Street": "Rumpsterweg",
                    "Zipcode": "3981AK",
                    "Remark": "Dit is een Afhaalpunt+. Pakketten die je op werkdagen
vóór lichtingstijd afgeeft, bezorgen we binnen Nederland de volgende dag. Je
kunt hier pakketten -  voorzien van scanbare barcode - versturen en pakketten
ophalen."
                },
                "DeliveryOptions": {
                    "string": [
                        "DO",
                        "PG",
                        "BW",
                        "BWUL",
                        "RT"
                    ]
                },
                "Distance": 1567,
                "Latitude": 52.06321379,
                "Longitude": 5.21485447,
                "LocationCode": 217364,
                "Name": "ASN Autoschade Boll",
                "PartnerName": "PostNL",
                "RetailNetworkID": "PNPNL-01",
                "OpeningHours": {
                    "Monday": {
                        "string": "08:00-17:00"
                    },
                    "Tuesday": {
                        "string": "08:00-17:00"
                    },
                    "Wednesday": {
                        "string": "08:00-17:00"
                    },
                    "Thursday": {
                        "string": "08:00-17:00"
                    },
                    "Friday": {
                        "string": "08:00-17:00"
                    },
                    "Saturday": {
                        "string": "09:00-12:00"
                    }
                }
            },
            {
                "Address": {
                    "City": "Houten",
                    "Countrycode": "NL",
                    "HouseNr": 57,
                    "HouseNrExt": "A",
                    "Street": "Odijkseweg",
                    "Zipcode": "3994AS",
                    "Remark": "Dit is een Pakketpunt. Pakketten die je op werkdagen
vóór lichtingstijd afgeeft, bezorgen we binnen Nederland de volgende dag.
Op zaterdag worden alléén pakketten die je afgeeft voor 15:00 uur maandag
bezorgd."
                },
                "DeliveryOptions": {
                    "string": [
                        "RETA",
                        "DO",
                        "PG",
                        "BW",
                        "BWUL",
                        "RT"
                    ]
                },
                "Distance": 2808,
                "Latitude": 52.03214975,
                "Longitude": 5.18059747,
                "LocationCode": 205786,
                "Name": "Jumbo",
                "PartnerName": "PostNL",
                "RetailNetworkID": "PNPNL-01",
                "OpeningHours": {
                    "Monday": {
                        "string": "08:00-21:00"
                    },
                    "Tuesday": {
                        "string": "08:00-21:00"
                    },
                    "Wednesday": {
                        "string": "08:00-21:00"
                    },
                    "Thursday": {
                        "string": "08:00-21:00"
                    },
                    "Friday": {
                        "string": "08:00-21:00"
                    },
                    "Saturday": {
                        "string": "07:00-20:00"
                    },
                    "Sunday": {
                        "string": "12:00-18:00"
                         }
                }
            }
        ]
    }
}

Request LocationsinArea:

curl --location --request GET 'https://api-sandbox.postnl.nl/shipment/v2_1/locations/
area?DeliveryDate=02-09-2022&maxLocations=5&OpeningTime=09:00:00&
DeliveryOptions=PG&Options=Daytime&CountryCode=NL&
LatitudeNorth=52.1057&LongitudeWest=5.14545&
LatitudeSouth=52.0057&LongitudeEast=5.24545' \
--header 'apikey: ***' \

Response (TRUNCATED): 

{
    "GetLocationsResult": {
        "ResponseLocation": [
            {
                "Address": {
                    "City": "Bunnik",
                    "Countrycode": "NL",
                    "HouseNr": 20,
                    "HouseNrExt": "-26",
                    "Street": "van Hardenbroeklaan",
                    "Zipcode": "3981EP",
                    "Remark": "Dit is een Postkantoor. Post en pakketten die je op werkdagen
vóór de lichtingstijd afgeeft, bezorgen we binnen Nederland de volgende dag. Op 
zaterdag worden alléén pakketten die je afgeeft voor 15:00 uur maandag bezorgd."
                },
                "DeliveryOptions": {
                    "string": [
                        "RETA",
                        "DO",
                        "PG",
                        "BW",
                        "BWUL",
                        "RT"
                    ]
                },
                "Distance": 1382,
                "Latitude": 52.06781104,
                "Longitude": 5.20001936,
                "LocationCode": 161616,
                "Name": "Boekhandel van Ravenswaaij",
                "PartnerName": "PostNL",
                "RetailNetworkID": "PNPNL-01",
                "OpeningHours": {
                    "Monday": {
                        "string": "09:00-18:00"
                    },
                    "Tuesday": {
                        "string": "09:00-18:00"
                    },
                    "Wednesday": {
                        "string": "09:00-18:00"
                    },
                    "Thursday": {
                        "string": "09:00-18:00"
                    },
                    "Friday": {
                        "string": "09:00-18:00"
                    },
                    "Saturday": {
                        "string": "09:00-17:00"
                    }
                }
            },
            {
                "Address": {
                    "City": "Bunnik",
                    "Countrycode": "NL",
                    "HouseNr": 20,
                    "Street": "Rumpsterweg",
                    "Zipcode": "3981AK",
                    "Remark": "Dit is een Afhaalpunt+. Pakketten die je op werkdagen
vóór lichtingstijd afgeeft, bezorgen we binnen Nederland de volgende dag.
Je kunt hier pakketten -  voorzien van scanbare barcode - versturen en pakketten ophalen."
                },
                "DeliveryOptions": {
                    "string": [
                        "DO",
                        "PG",
                        "BW",
                        "BWUL",
                        "RT"
                    ]
                },
                "Distance": 1567,
                "Latitude": 52.06321379,
                "Longitude": 5.21485447,
                "LocationCode": 217364,
                "Name": "ASN Autoschade Boll",
                "PartnerName": "PostNL",
                "RetailNetworkID": "PNPNL-01",
                "OpeningHours": {
                    "Monday": {
                        "string": "08:00-17:00"
                    },
                    "Tuesday": {
                        "string": "08:00-17:00"
                    },
                    "Wednesday": {
                        "string": "08:00-17:00"
                    },
                    "Thursday": {
                        "string": "08:00-17:00"
                    },
                    "Friday": {
                        "string": "08:00-17:00"
                    },
                    "Saturday": {
                        "string": "09:00-12:00"
                    }
                }
            },
            {
                "Address": {
                    "City": "Houten",
                    "Countrycode": "NL",
                    "HouseNr": 57,
                    "HouseNrExt": "A",
                    "Street": "Odijkseweg",
                    "Zipcode": "3994AS",
                    "Remark": "Dit is een Pakketpunt. Pakketten die je op werkdagen
vóór lichtingstijd afgeeft, bezorgen we binnen Nederland de volgende dag. 
Op zaterdag worden alléén pakketten die je afgeeft voor 15:00 uur maandag bezorgd."
                },
                "DeliveryOptions": {
                    "string": [
                        "RETA",
                        "DO",
                        "PG",
                        "BW",
                        "BWUL",
                        "RT"
                    ]
                },
                "Distance": 2808,
                "Latitude": 52.03214975,
                "Longitude": 5.18059747,
                "LocationCode": 205786,
                "Name": "Jumbo",
                "PartnerName": "PostNL",
                "RetailNetworkID": "PNPNL-01",
                "OpeningHours": {
                    "Monday": {
                        "string": "08:00-21:00"
                    },
                    "Tuesday": {
                        "string": "08:00-21:00"
                    },
                    "Wednesday": {
                        "string": "08:00-21:00"
                    },
                    "Thursday": {
                        "string": "08:00-21:00"
                    },
                    "Friday": {
                        "string": "08:00-21:00"
                    },
                    "Saturday": {
                        "string": "07:00-20:00"
                    },
                    "Sunday": {
                        "string": "12:00-18:00"
                          }
                }
            }
        ]
    }
}

Request Location lookup:

curl --location --request GET 'https://api-sandbox.postnl.nl/shipment/v2_1/locations/lookup?
LocationCode=220718&RetailNetworkID=PNPNL-01' \
--header 'apikey: ***' \

Response:

{
    "GetLocationsResult": {
        "ResponseLocation": {
            "Address": {
                "City": "'s-Gravenhage",
                "Countrycode": "NL",
                "HouseNr": 30,
                "HouseNrExt": "PBA",
                "Street": "Amsterdamse Veerkade",
                "Zipcode": "2512AJ"
            },
            "DeliveryOptions": {
                "string": [
                    "DO",
                    "PG",
                    "PBA"
                ]
            },
            "Latitude": 52.07526049,
            "Longitude": 4.31596288,
            "LocationCode": 220718,
            "Name": "Pakket- en Briefautomaat",
            "PartnerName": "PostNL",
            "RetailNetworkID": "PNPNL-01",
            "OpeningHours": {
                "Monday": {
                    "string": "00:00-23:59"
                },
                "Tuesday": {
                    "string": "00:00-23:59"
                },
                "Wednesday": {
                    "string": "00:00-23:59"
                },
                "Thursday": {
                    "string": "00:00-23:59"
                },
                "Friday": {
                    "string": "00:00-23:59"
                },
                "Saturday": {
                    "string": "00:00-23:59"
                },
                "Sunday": {
                    "string": "00:00-23:59"
                }
            }
        }
    }
}

Request GetNearestLocations

Countrycode type

AttributeMandatoryFormatDescriptionExample
CountrycodeMString [2] The ISO2 country codes Always NL for Dutch locations. For Belgium locations use BE.NL

Location type

AttributeMandatoryFormatDescriptionExample
AllowSundaySortingMBoolean [true/false]Whether or not the requesting party allows for Sunday sorting (which leads to delivery on Monday).true
DeliveryDateMDate [10] The date of the earliest delivery date. Format:  dd-mm-yyyy
Note: this date cannot be in the past, otherwise an error is returned.
29-06-2016
DeliveryOptionsMString [2-3] One or more delivery options (related to the product). See Guidelines on this page for possible values.PG
OptionsMString [1-15]The delivery options (timeframes) for which locations should
be returned. 
Daytime
OpeningTimeOTime [8]Time of opening. Format: hh:mm:ss. This field will be used to filter the locations on opening hours.09:00:00
CoordinatesO-MDouble [1-15]The coordinates of the location.
Mandatory when postal code is empty. Latitude / Longitude. 
52.290344
4.7086662
CityOString [0-35] City of the address  Hoofddorp
HouseNr.OString [0-35] The house number of the delivery address42
HouseNrExtOString [0-35] House number extension A
PostalcodeO-MString [4-10] Zipcode of the address
Mandatory when no coordinates are entered
2132WT
StreetOString [0-95] The street name of the delivery addressSiriusdreef

Message type

AttributeMandatoryFormatDescriptionExample
MessageIDMString [1-12] ID of the message.1
MessageTimeStampMDatetime [19] Date/time of sending the message. Format:  dd-mm-yyyy hh:mm:ss 29-06-2016 12:00:00

Response GetNearestLocations

Address type

Attribute  DescriptionExample
Area  Area of the addressBeukenhorst
Buildingname  Name of the building of the addressAA
City  City of the addressHoofddorp
Countrycode  The ISO2 country codes NL 
Department  Specific department of a companyIT
Doorcode  Door code of address123
Floor  Specific floor of a company4
HouseNr  Housenumber of the address 10
HouseNrExt  House number extension A
Remark   Remark of the location Dit is een Business Point. Post en pakketten die u op werkdagen vóór de lichtingstijd afgeeft, bezorgen we binnen Nederland de volgende dag.
Street  The streetname of the addressJacobus Spijkerdreef
Zipcode  The zipcode of the address2132PZ

Deliveryoptions type

AttributeMandatoryFormatDescriptionExample
Deliveryoptions  One or more delivery options. See the Guidelines for possible values. PG

Location type

Attribute  DescriptionExample
Distance   The distance from this location to the address entered in the request (in meters).355
Latitude   The latitude of the location52.2864669620795
LocationCode  LocationCode information173187
Longitude  The longitude of the location4.68239055845954
Name  Name of the location Gamma
Openingshours  Openinghours of the location, split by Day. 08:00-18:30
PartnerName  Partnername of the locationPostNL
PhoneNumber  Phone number of the location023-5576310
RetailNetworkID  The network ID used for this retail locationPNPNL-01
Saleschannel  The sales channel used for this locationPKT XL
TerminalType  The terminal type used by this locationNRS

Warning type

Attribute  DescriptionExample
Code  Code of the warning501
Description  Description of the warningNo locations found

Request GetLocationsInArea

Countrycode type

AttributeMandatoryFormatDescriptionExample
CountrycodeMString [2] The ISO2 country codes NL 

Location type

AttributeMandatoryFormatDescriptionExample
DeliveryDateMDate [10] The date of the earliest delivery date. Format: dd-mm-yyyy
Note: this date cannot be in the past, otherwise an error is returned.
29-06-2016
DeliveryOptionsMString [2-3] The delivery options (timeframes) for which locations should
be returned. See  Guidelines
PG
OptionsMString [1-15]The delivery options (timeframes) for which locations should
be returned. See Guidelines for possible values.
Daytime
OpeningTimeOTime [8]Time of opening. Format: hh:mm:ss. This field will be used to filter the locations on opening hours.09:00:00
CoordinatesNorthWestMDouble [1-15]The coordinates of the north west point of the area.
Latitude / Longitude.
52.156439
5.015643
CoordinatesSouthEastMDouble [1-15]The coordinates of the south east point of the area.
Latitude / Longitude.
52.017473
5.065254

Message type

AttributeMandatoryFormatDescriptionExample
MessageIDMString [1-12] ID of the message.1
MessageTimeStampMDatetime [19] Date/time of sending the message. Format: dd-mm-yyyy hh:mm:ss 29-06-2016 12:00:00

Response GetLocationsInArea

Attribute  DescriptionExample
Area  Area of the addressOudenrijn
Buildingname  Name of the building of the addressB tower
City  City of the address  de Meern
Countrycode  The ISO2 country codes NL 
Department  Specific department of a companyIT
Doorcode  Door code of address123
Floor  Specific floor of a company4
HouseNr  Housenumber of the address 22
HouseNrExt  House number extension A
Remark   Remark of the location Brieven en pakketten die je ma t/m vr afgeeft, worden uiterlijk om 18.00 uur dezelfde dag opgehaald voor bezorging. 
Street  The streetname of the addressMereveldplein
Zipcode  The zipcode of the address3454CK

Deliveryoptions type

Attribute  DescriptionExample
Deliveryoptions  One or more delivery options. See Guidelines for possible values. DO,PG

Location type

Attribute  DescriptionExample
Distance   The distance from this location to the address entered in the request (in meters)355
Latitude   The latitude of the location52.0794943427349
LocationCode  LocationCode information175812
Longitude  The longitude of the location5.03762153082277
Name  Name of the location Kantoorboekhandel Kees Visscher
Openingshours  Openinghours of the location, split by Day. 07:00-22:00
PartnerName  Partnername of the locationPostNL
PhoneNumber  Phone number of the location030-6662230
RetailNetworkID  The network ID used for this retail locationPNPNL-01
Saleschannel  The sales channel used for this locationPKT XL
TerminalType  The terminal type used by this locationNRS

Warning type

Attribute  DescriptionExample
Code  Code of the warning501
Description  Description of the warningNo locations found

Request GetLocation

Location type

AttributeMandatoryFormatDescriptionExample
LocationCode MString [1-12] LocationCode information161503
RetailNetworkIDMString [8]RetailNetworkID information. Always PNPNL-01 for Dutch locations. For Belgium locations use PNPBE-01 (use the RetailNetworkID from the API call response). PNPNL-01

Message type

AttributeMandatoryFormatDescriptionExample
MessageIDMString [1-12] ID of the message.1
MessageTimeStampMDatetime [19] Date/time of sending the message. Format:  dd-mm-yyyy hh:mm:ss 29-06-2016 12:00:00