Documentation

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 (GET)

Description

GetNearestLocations

Returns locations nearest to the supplied location.

GetLocationsInArea

Returns locations within the supplied area.

GetLocation

Returns location information of the supplied location code.

Method

SoapAction

GetNearestLocations

http://postnl.nl/cif/services/LocationWebService/ILocationWebService/GetNearestLocations

GetLocationsInArea

http://postnl.nl/cif/services/LocationWebService/ILocationWebService/GetLocationsInArea

GetLocation

http://postnl.nl/cif/services/LocationWebService/ILocationWebService/GetLocation

Call details

Interface version 2_1
Sandbox endpointhttps://api-sandbox.postnl.nl/shipment/v2_1/locations
Sandbox wsdl https://api-sandbox.postnl.nl/shipment/v2_1/locations/soap.wsdl
Sandbox swaggerhttps://api-sandbox.postnl.nl/shipment/v2_1/locations/swagger.json
Production endpointhttps://api.postnl.nl/shipment/v2_1/locations
Production wsdlhttps://api.postnl.nl/shipment/v2_1/locations/soap.wsdl 
Production swaggerhttps://api.postnl.nl/shipment/v2_2/locations/swagger.json

* PostNL has launched a new API platform since 24 August 2017. The former webservices have been migrated to this platform, so that we can keep providing good service. It is recommended to use the above endpoints.

If you already use the former API’s (endpoint: https://service.postnl.com/CIF/) and you want to make use of the new endpoints, you can fill in the Request for API key form or contact your PostNL account manager to arrange this.

Versioning

REST:

API

Version

Release Date

Status

Release Notes

Schema Changes

Location

2_1

May 10, 2016

Current version

IN COMPARISON TO THE 2_0 SOAP VERSION,
the Location Type has been extended with PartnerLocationCodes (ResponseLocationCode).

 N/A

SOAP:

API

 

Version

Release Date

Status

Release Notes

Schema Changes

Location

1_0

Jul 22, 2013

Not supported

 

 

1_1

Aug 21, 2014

Supported

Different namespaces
The operation GetNearestLocations has been updated with new request properties:

  • Countrycode [M] has been added for international locations
  • Location\City [O] has been added for better international matching
  • Location\HouseNr [O] has been added for better international matching
  • Location\HouseNrExt [O] has been added for better international matching
  • Location\Street [O] has been added for better international matching

The operation GetLocationsInArea has been updated with new request properties:

  • Countrycode [M] has been added for international locations

The operation GetBLSLocation has been removed

The operation GetLocation has been added

The Location Type has been extended with international address properties.

Yes

2_0

Aug 14, 2015

Not supported

A number of new fields have been added to the data types. To access these new fields, a new webservice client has to be generated based on the new WSDL version.
  • Sunday sorting and options added
    It is now possible to specifiy AllowSundaySorting and Options when searching for locations using the GetNearestLocations and GetLocationsInArea methods.
  • Partner name and retail formula name added
    Found locations will now include the distribution network partner name and the retail formula name in the PartnerName and RetailFormulaName fields, if these are known for the location. 
  • Warning added
    The methods GetNearestLocations and GetLocationsInArea will now return a warning when no locations could be found that match the specified search criteria.

Yes

 2_1May 10, 2016Current Version

The Location Type has been extended with PartnerLocationCodes (ResponseLocationCode).

No

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 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 GetNearestLocations

Countrycode type

AttributeMandatoryFormatDescriptionExample
CountrycodeMString [2] The ISO2 country codes Always PNPNL-01 for Dutch locations. For Belgium locations use LD-01.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.PGE
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

Example

POST https://api-sandbox.postnl.nl/shipment/v2_1/locations HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: text/xml;charset=UTF-8
SOAPAction: "http://postnl.nl/cif/services/LocationWebService/ILocationWebService/GetNearestLocations"
apikey: **********
Content-Length: 1834
Connection: Keep-Alive

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:loc="http://postnl.nl/cif/services/LocationWebService/" xmlns:tpp="http://postnl.nl/cif/domain/LocationWebService/" xmlns:arr="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
  <soapenv:Body>
    <loc:GetNearestLocations>
      <tpp:Countrycode>NL</tpp:Countrycode>
      <tpp:Location>
        <tpp:AllowSundaySorting>true</tpp:AllowSundaySorting>
        <tpp:DeliveryDate>29-06-2016</tpp:DeliveryDate>
        <tpp:DeliveryOptions>
          <arr:string>PGE</arr:string>
        </tpp:DeliveryOptions>
        <tpp:OpeningTime>09:00:00</tpp:OpeningTime>
        <tpp:Options>
          <arr:string>Daytime</arr:string>
        </tpp:Options>
        <tpp:City>Hoofddorp</tpp:City>          
        <tpp:HouseNr>42</tpp:HouseNr>
        <tpp:HouseNrExt>A</tpp:HouseNrExt>
        <tpp:Postalcode>2132WT</tpp:Postalcode>
        <tpp:Street>Siriusdreef</tpp:Street>          
      </tpp:Location>
      <tpp:Message>
        <tpp:MessageID>1</tpp:MessageID>
        <tpp:MessageTimeStamp>29-06-2016 12:00:00</tpp:MessageTimeStamp>
      </tpp:Message>
    </loc:GetNearestLocations>
  </soapenv:Body>
</soapenv:Envelope>

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

Example

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Body>
    <GetNearestLocationsResponse xmlns="http://postnl.nl/cif/services/LocationWebService/"
xmlns:a="http://postnl.nl/cif/domain/LocationWebService/"
xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
      <a:GetLocationsResult>
        <a:ResponseLocation>
          <a:Address>
            <a:City>Hoofddorp</a:City>
            <a:Countrycode>NL</a:Countrycode>
            <a:HouseNr>10</a:HouseNr>
            <a:Remark>Dit is een Business Point. Post en pakketten die u op werkdagen vóór de lichtingstijd afgeeft, bezorgen we binnen Nederland de volgende dag.</a:Remark>
            <a:Street>Jacobus Spijkerdreef</a:Street>
            <a:Zipcode>2132PZ</a:Zipcode>
          </a:Address>
          <a:DeliveryOptions xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
            <b:string>DO</b:string>
            <b:string>PG</b:string>
            <b:string>PGE</b:string>
            <b:string>UL</b:string>
          </a:DeliveryOptions>
          <a:Distance>355</a:Distance>
          <a:Latitude>52.2864669620795</a:Latitude>
          <a:LocationCode>173187</a:LocationCode>
          <a:Longitude>4.68239055845954</a:Longitude>
          <a:Name>Gamma</a:Name>
          <a:OpeningHours>
            <a:Friday xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
              <b:string>08:00-18:30</b:string>
            </a:Friday>
            <a:Monday xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
              <b:string>08:00-18:30</b:string>
            </a:Monday>
            <a:Saturday xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
              <b:string>08:00-17:00</b:string>
            </a:Saturday>
            <a:Thursday xmlns:b=http://schemas.microsoft.com/2003/10/Serialization/Arrays>
              <b:string>08:00-18:30</b:string>
            </a:Thursday>
            <a:Tuesday xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
              <b:string>08:00-18:30</b:string>
            </a:Tuesday>
            <a:Wednesday xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
              <b:string>08:00-18:30</b:string>
            </a:Wednesday>
          </a:OpeningHours>
          <a:PartnerName>PostNL</a:PartnerName>
          <a:PhoneNumber>023-5576310</a:PhoneNumber>
          <a:RetailNetworkID>PNPNL-01</a:RetailNetworkID>
          <a:Saleschannel>PKT XL</a:Saleschannel>
          <a:TerminalType>NRS</a:TerminalType>
        </a:ResponseLocation>
      </a:GetLocationsResult>
    </GetNearestLocationsResponse>
  </s:Body>
</s:Envelope>

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

Example

POST https://api-sandbox.postnl.nl/shipment/v2_1/locations HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: text/xml;charset=UTF-8
SOAPAction: "http://postnl.nl/cif/services/LocationWebService/ILocationWebService/GetLocationsInArea"
apikey: **********
Content-Length: 1805
Connection: Keep-Alive


<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:loc="http://postnl.nl/cif/services/LocationWebService/" xmlns:tpp="http://postnl.nl/cif/domain/LocationWebService/" xmlns:arr="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
  <soapenv:Body>
    <loc:GetLocationsInArea>
      <tpp:Countrycode>NL</tpp:Countrycode>
      <tpp:Location>
        <tpp:AllowSundaySorting>true</tpp:AllowSundaySorting>
        <tpp:DeliveryDate>29-06-2016</tpp:DeliveryDate>
        <tpp:DeliveryOptions>
          <arr:string>PG</arr:string>
        </tpp:DeliveryOptions>
        <tpp:OpeningTime>09:00:00</tpp:OpeningTime>
        <tpp:Options>
          <arr:string>Daytime</arr:string>
        </tpp:Options>
        <tpp:CoordinatesNorthWest>
          <tpp:Latitude>52.156439</tpp:Latitude>
          <tpp:Longitude>5.015643</tpp:Longitude>
        </tpp:CoordinatesNorthWest>
        <tpp:CoordinatesSouthEast>
          <tpp:Latitude>52.017473</tpp:Latitude>
          <tpp:Longitude>5.065254</tpp:Longitude>
        </tpp:CoordinatesSouthEast>
      </tpp:Location>
      <tpp:Message>
        <tpp:MessageID>1</tpp:MessageID>
        <tpp:MessageTimeStamp>29-06-2016 12:00:00</tpp:MessageTimeStamp>
      </tpp:Message>
    </loc:GetLocationsInArea>
  </soapenv:Body>
</soapenv:Envelope>

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

Example

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
   <s:Body>
      <GetLocationsInAreaResponse xmlns="http://postnl.nl/cif/services/LocationWebService/"
xmlns:a="http://postnl.nl/cif/domain/LocationWebService/"
xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
         <a:GetLocationsResult>
            <a:ResponseLocation>
               <a:Address>
                  <a:City>de Meern</a:City>
                  <a:Countrycode>NL</a:Countrycode>
                  <a:HouseNr>22</a:HouseNr>
                  <a:Remark><b>Brieven en pakketten die je ma t/m vr afgeeft, worden uiterlijk om 18.00 uur dezelfde dag opgehaald voor bezorging </b></a:Remark>
                  <a:Street>Mereveldplein</a:Street>
                  <a:Zipcode>3454CK</a:Zipcode>
               </a:Address>
               <a:DeliveryOptions xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
                  <b:string>DO</b:string>
                  <b:string>PG</b:string>
                  <b:string>UL</b:string>
               </a:DeliveryOptions>
               <a:Distance>355</a:Distance>
               <a:Latitude>52.0794943427349</a:Latitude>
               <a:LocationCode>175812</a:LocationCode>
               <a:Longitude>5.03762153082277</a:Longitude>
               <a:Name>Kantoorboekhandel Kees Visscher</a:Name>
               <a:OpeningHours>
                  <a:Friday xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
                     <b:string>08:30-18:00</b:string>
                  </a:Friday>
                  <a:Monday xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
                     <b:string>08:30-18:00</b:string>
                  </a:Monday>
                  <a:Saturday xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
                     <b:string>08:30-17:00</b:string>
                  </a:Saturday>
                  <a:Thursday xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
                     <b:string>08:30-18:00</b:string>
                  </a:Thursday>
                  <a:Tuesday xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
                     <b:string>08:30-18:00</b:string>
                  </a:Tuesday>
                  <a:Wednesday xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
                     <b:string>08:30-18:00</b:string>
                  </a:Wednesday>
               </a:OpeningHours>
               <a:PhoneNumber>030-6662230</a:PhoneNumber>
               <a:RetailNetworkID>PNPNL-01</a:RetailNetworkID>
               <a:Saleschannel>PKT M</a:Saleschannel>
               <a:TerminalType>NRS</a:TerminalType>
            </a:ResponseLocation>
      </GetLocationsInAreaResponse>
   </s:Body>
</s:Envelope>

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 LD-01.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

Example

POST https://api-sandbox.postnl.nl/shipment/v2_1/locations HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: text/xml;charset=UTF-8
SOAPAction: "http://postnl.nl/cif/services/LocationWebService/ILocationWebService/GetLocation"
apikey: **********
Content-Length: 970
Connection: Keep-Alive


<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:loc="http://postnl.nl/cif/services/LocationWebService/" xmlns:tpp="http://postnl.nl/cif/domain/LocationWebService/">
  <soapenv:Body>
    <loc:GetLocation>
      <tpp:LocationCode>161503</tpp:LocationCode>
      <tpp:Message>
        <tpp:MessageID>1</tpp:MessageID>
        <tpp:MessageTimeStamp>29-06-2016 12:00:00</tpp:MessageTimeStamp>
      </tpp:Message>
      <tpp:RetailNetworkID>PNPNL-01</tpp:RetailNetworkID>
    </loc:GetLocation>
  </soapenv:Body>
</soapenv:Envelope>