3 Find parcel shop location

3.1 Intro

The Parcel shop finder endpoint makes it possible to find parcel shops or DHL Servicepoints in a country based on address information and or a wildcard.

Preconditions

No preconditions are applicable.

3.2 Services

3.2.1 Find the nearest parcel shop location endpoint

The Find the nearest parcel shop location endpoint gets you a list of the nearby DHL Servicepoints based on the country code and address information or a wildcard (q) like a piece of the recipient’s address e.q. city and or name or the postal code of an address.

So in order to get a list of parcel shops the country code is required and at least one of these fields: free format location description, postal code, city.

Field	Description
q	free format location description, where multiple keywords can be entered. For example country code ‘NL’ and keywords ‘Tabak’ and ‘1055’ will return a parcel shop in Amsterdam (postal code with 1055 in it) and that has ‘Tabak’ in its name.
zipCode	format depends on the country e.g. for the country code ‘NL’ it is ‘9999XX’, ‘ES’ is is ‘99999’ etc.

The more specific the address is the less DHL Servicepoints will be returned and the more accurate the result is. A query based on just the street name will not suffice. There is the option to limit the result with the input field ‘limit’.

The result is ordered ascending based on the geo location, meaning the nearest DHL ServicePoint is at the top.

The response contains the identification of a DHL ServicePoint. This id serves as extra input in the shipment option as explained in 3.3.1 Create Label when sending a shipment to a DHL ServicePoint.

3.2.2 Get specific DHL Servicepoint

The Find the information for a specific parcel shop location endpoint allows you to select a specific DHL ServicePoint. The country code is mandatory and the DHL ServicePoint id is needed. This id can be queried by using the Find the nearest parcel shop location endpoint.

3.3 API Usage

Description	URL
Endpoint to get nearest parcel shops	https://api-gw.dhlparcel.nl/parcel-shop-locations/<countrycode>?
Endpoint to get specific parcel shop	https://api-gw.dhlparcel.nl/parcel-shop-locations/<countrycode>/<parcelshopId>

3.3.1 Get nearest parcel shops

Request examples

Curl

curl - X GET "https://api-gw.dhlparcel.nl/parcel-shop-locations/ES?city=Madrid&showUnavailable=false" - H "Accept: application/json"

Response

Success (code 200)

[
  {
    "id": "5017-ES-0000104",
    "harmonisedId": "101",
    "psfKey": "ES-0000104",
    "shopType": "parcelShop",
    "name": "FOLDER PLAZA DEL ANGEL",
    "keyword": "DHL ServicePoint",
    "address": {
      "countryCode": "ES",
      "zipCode": "28012",
      "postalCode": "28012",
      "city": "MADRID",
      "street": "C/ PLAZA DEL ANGEL",
      "number": "16",
      "isBusiness": true
    },
    "geoLocation": {
      "latitude": 40.414381,
      "longitude": -3.702893
    },
    "distance": 284,
    "openingTimes": [
      {
        "timeFrom": "10:00:00.000",
        "timeTo": "14:00:00.000",
        "weekDay": 1
      },
      {
        "timeFrom": "17:00:00.000",
        "timeTo": "20:30:00.000",
        "weekDay": 1
      },
      {
        "timeFrom": "10:00:00.000",
        "timeTo": "14:00:00.000",
        "weekDay": 2
      },
      {
        "timeFrom": "17:00:00.000",
        "timeTo": "20:30:00.000",
        "weekDay": 2
      },
      {
        "timeFrom": "10:00:00.000",
        "timeTo": "14:00:00.000",
        "weekDay": 3
      },
      {
        "timeFrom": "17:00:00.000",
        "timeTo": "20:30:00.000",
        "weekDay": 3
      },
      {
        "timeFrom": "10:00:00.000",
        "timeTo": "14:00:00.000",
        "weekDay": 4
      },
      {
        "timeFrom": "17:00:00.000",
        "timeTo": "20:30:00.000",
        "weekDay": 4
      },
      {
        "timeFrom": "10:00:00.000",
        "timeTo": "14:00:00.000",
        "weekDay": 5
      },
      {
        "timeFrom": "17:00:00.000",
        "timeTo": "20:30:00.000",
        "weekDay": 5
      },
      {
        "timeFrom": "10:00:00.000",
        "timeTo": "14:00:00.000",
        "weekDay": 6
      },
      {
        "timeFrom": "16:30:00.000",
        "timeTo": "20:30:00.000",
        "weekDay": 6
      }
    ],
    "closurePeriods": []
  },
  {
    "id": "5017-ES-0001288",
    "harmonisedId": "101",
    "psfKey": "ES-0001288",
    "shopType": "parcelShop",
    "name": "WORKCENTER C/ SEVILLA",
    "keyword": "DHL ServicePoint",
    "address": {
      "countryCode": "ES",
      "zipCode": "28014",
      "postalCode": "28014",
      "city": "MADRID",
      "street": "C/ SEVILLA",
      "number": "4",
      "isBusiness": true
    },
    "geoLocation": {
      "latitude": 40.417446,
      "longitude": -3.699818
    },
    "distance": 446,
    "openingTimes": [
      {
        "timeFrom": "08:00:00.000",
        "timeTo": "21:00:00.000",
        "weekDay": 1
      },
      {
        "timeFrom": "08:00:00.000",
        "timeTo": "21:00:00.000",
        "weekDay": 2
      },
      {
        "timeFrom": "08:00:00.000",
        "timeTo": "21:00:00.000",
        "weekDay": 3
      },
      {
        "timeFrom": "08:00:00.000",
        "timeTo": "21:00:00.000",
        "weekDay": 4
      },
      {
        "timeFrom": "08:00:00.000",
        "timeTo": "21:00:00.000",
        "weekDay": 5
      },
      {
        "timeFrom": "10:00:00.000",
        "timeTo": "14:30:00.000",
        "weekDay": 6
      },
      {
        "timeFrom": "17:00:00.000",
        "timeTo": "20:30:00.000",
        "weekDay": 6
      },
      {
        "timeFrom": "11:00:00.000",
        "timeTo": "14:30:00.000",
        "weekDay": 7
      },
      {
        "timeFrom": "17:00:00.000",
        "timeTo": "21:30:00.000",
        "weekDay": 7
      }
    ],
    "closurePeriods": []
  },
  {
    "id": "5017-ES-0002224",
    "harmonisedId": "101",
    "psfKey": "ES-0002224",
    "shopType": "parcelShop",
    "name": "INFINITY COMICS",
    "keyword": "DHL ServicePoint",
    "address": {
      "countryCode": "ES",
      "zipCode": "28013",
      "postalCode": "28013",
      "city": "MADRID",
      "street": "C/ HILERAS",
      "number": "2",
      "isBusiness": true
    },
    "geoLocation": {
      "latitude": 40.416814,
      "longitude": -3.708361
    },
    "distance": 505,
    "openingTimes": [
      {
        "timeFrom": "11:00:00.000",
        "timeTo": "14:00:00.000",
        "weekDay": 1
      },
      {
        "timeFrom": "17:00:00.000",
        "timeTo": "20:30:00.000",
        "weekDay": 1
      },
      {
        "timeFrom": "11:00:00.000",
        "timeTo": "14:00:00.000",
        "weekDay": 2
      },
      {
        "timeFrom": "17:00:00.000",
        "timeTo": "20:30:00.000",
        "weekDay": 2
      },
      {
        "timeFrom": "11:00:00.000",
        "timeTo": "14:00:00.000",
        "weekDay": 3
      },
      {
        "timeFrom": "17:00:00.000",
        "timeTo": "20:30:00.000",
        "weekDay": 3
      },
      {
        "timeFrom": "11:00:00.000",
        "timeTo": "14:00:00.000",
        "weekDay": 5
      },
      {
        "timeFrom": "17:00:00.000",
        "timeTo": "20:30:00.000",
        "weekDay": 5
      },
      {
        "timeFrom": "11:00:00.000",
        "timeTo": "14:00:00.000",
        "weekDay": 6
      },
      {
        "timeFrom": "17:00:00.000",
        "timeTo": "20:30:00.000",
        "weekDay": 6
      }
    ],
    "closurePeriods": []
  }
]

3.3.2 Get specific parcel shop

Request examples

Curl

curl - X GET "https://api-gw.dhlparcel.nl/parcel-shop-locations/ES/5017-ES- 0000104 " -H "Accept: application/json"

Responses

Success (code 200)

{
  "id": "5017-ES-0000104",
  "harmonisedId": "101",
  "psfKey": "ES-0000104",
  "shopType": "parcelShop",
  "name": "FOLDER PLAZA DEL ANGEL",
  "keyword": "DHL ServicePoint",
  "address": {
    "countryCode": "ES",
    "zipCode": "28012",
    "postalCode": "28012",
    "city": "MADRID",
    "street": "C/ PLAZA DEL ANGEL",
    "number": "16",
    "isBusiness": true
  },
  "geoLocation": {
    "latitude": 40.414381,
    "longitude": -3.702893
  },
  "openingTimes": [
    {
      "timeFrom": "10:00:00.000",
      "timeTo": "14:00:00.000",
      "weekDay": 1
    },
    {
      "timeFrom": "17:00:00.000",
      "timeTo": "20:30:00.000",
      "weekDay": 1
    },
    {
      "timeFrom": "10:00:00.000",
      "timeTo": "14:00:00.000",
      "weekDay": 2
    },
    {
      "timeFrom": "17:00:00.000",
      "timeTo": "20:30:00.000",
      "weekDay": 2
    },
    {
      "timeFrom": "10:00:00.000",
      "timeTo": "14:00:00.000",
      "weekDay": 3
    },
    {
      "timeFrom": "17:00:00.000",
      "timeTo": "20:30:00.000",
      "weekDay": 3
    },
    {
      "timeFrom": "10:00:00.000",
      "timeTo": "14:00:00.000",
      "weekDay": 4
    },
    {
      "timeFrom": "17:00:00.000",
      "timeTo": "20:30:00.000",
      "weekDay": 4
    },
    {
      "timeFrom": "10:00:00.000",
      "timeTo": "14:00:00.000",
      "weekDay": 5
    },
    {
      "timeFrom": "17:00:00.000",
      "timeTo": "20:30:00.000",
      "weekDay": 5
    },
    {
      "timeFrom": "10:00:00.000",
      "timeTo": "14:00:00.000",
      "weekDay": 6
    },
    {
      "timeFrom": "16:30:00.000",
      "timeTo": "20:30:00.000",
      "weekDay": 6
    }
  ],
  "closurePeriods": []
}

3.4 Testing

These test cases with positive outcomes are merely suggestions and it is not an extensive test set, e.g. tests with a negative outcome should also be taken into scope. Please extend with test cases which are suitable for your line of business or wishes.

Suggested Test Cases	Expected Result
Place a request limit to 3 for specific country code and place	Three parcel shops are returned in the given place by the Find the nearest parcel shop location endpoint
Place a request with the ID of a parcel shop	The given parcel shop is returned by the Find the information for a specific parcel shop location endpoint.