Shipment Tracking - Unified
v 1.4.1
Division: DHL Group

Die beste API für :

  • Zugriff auf den aktzellen Sendungsstatus 
  • Integration aller Arten von Deutsche Post DHL-Sendungen
  • Mehrere Sendungen (z. B. E-Commerce, Express, Fracht, Brief, Paket usw.)
Region: Global
Used for: Verfolgung
Overview

Die Sendungsverfolgungs-API bietet minutengenaue Sendungsstatusberichte. Benutzer dieser API können:

  • Tracking-Informationen für Sendungen abrufen
  • an der Sendung beteiligten Dienstleister von Deutsche Post DHL (DHL) Identifizieren
  • sicher stellen, dass DHL die richtige Lieferadresse verwendet. Dadurch kann die Anzahl falsch zugestellter Sendungen reduziert werden.

 

Umfang

Diese API deckt folgende Dienste / Produkte ab, die von DPDHL unter diesen Markennamen bereitgestellt werden:

  • Post & Parcel Germany
    • Einschreiben National, Einschreiben, Einschreiben Rückschein, Einschreiben Eigenhändig, Einschreiben Einwurf, Wert, Prio, Nachname, Einschreiben International, Einschreiben Rückschein International, Einschreiben Eigenhändig International, Wert National, Warenpost Tracked International, Ländernachweis, Postzustellungsauftäge (PZA),
    • Internetmarke
    • Paket
       
  • DHL Express
    • DHL Express 9:00, DHL Express 10:30, DHL Express 12:00, DHL Express Worldwide, DHL Express Envelope, DHL Express Easy, DHL Economy Select, DHL Express Domestic 9:00, DHL Express Domestic 10:30, DHL Express Domestic 12:00, DHL Express Domestic 18:00, DHL Medical Express, DHL Express Breakbulk
       
  • DHL Global Forwarding (incl. DHL Same Day)
    • AirFreight, OceanFreight Shipments
    • SameDay: SameDay Jetline Unaccompanied shipment, SameDay Jetline accompanied shipment, Same Day Speedline, SameDay Sprintline 
    • eCommerce shipments
       
  • DHL Freight
    • EuroConnect, Eurapid, EuroLine, EuroNet, Customs Services, Coldchain,Trade Fairs & Events, Standard Pallet Domestic, Premium Pallet Domestic, Lead Logistics Provider, Transport Related Warehousing, RailConnect, RailLine, Parcel, Home Delivery
       
  • DHL eCommerce Solutions
    • EU (Belgium, Luxemburg, Netherlands, Poland, Portugal, Spain)
      • Cross-border products (Parcel Connect, Return Connect, Parcel International, Connect PLUS, Return International) 
    • US, Canada:
      • Domestic Ground, Expedited, Expedited Max, Parcel International, Packet International
         
    • Asia-Pacific Domestic Shipments Data for Thailand & Malaysia
       
    • Parcel UK: 
      • Parcel Connect, Return Connect, Worldwide Air, Parcel International, International Road Economy  
         
  • DHL Supply Chain

Es umfasst nicht:

  • Services die einen Login benötigen z.B. B2B Systeme

The API provides users with tracking information on:

  • Shipment location
  • Shipment delivery time*
  • Shipment travel history*
  • The Proof of Delivery*
  • Shipment timestamp
  • Origin and destination information
  • Shipment number of pieces*
  • Shipment piece level events*
  • Shipment dimensions*
  • Shipment weight*

* Not available for all DPDHL services.

 

Using the API

You must have an eligible tracking code for the shipment and an API subscription key (this key needs to be specified in the request header).

 

Example Use Cases
 

Find the location of a shipment

You can use the API to help you build a website or application that enables DPDHL customers to see the location of their shipment.

The API will also identify the DPDHL service provider involved.


Discover when a shipment will arrive 

You can use the API to help you build a website or application that enables DPDHL customers to see when they can expect a delivery.

The system will also identify the DPDHL service provider involved.

 

Discover where a shipment has been (location history)

Some customers want to know their shipments’ travel history. 

You can use the API to help you build a website or application that enables DPDHL customers to see location history information such as:

  • The timestamps 
  • The locations traveled

The API will also identify the DPDHL service provider involved.

 

Check if DPDHL will ship to the correct address

You can help DPDHL customers verify the DPDHL service provider is using the correct delivery address. 

You can use the API to build query forms where users needs to enter the Tracking ID for a shipment. 

 

Discover which DPDHL service I used

You can help DPDHL customers find out which DPDHL service provider is delivering their shipment. 

You can use the API to build query forms where users needs to enter the Tracking ID for a shipment. 

 

Get the Proof of Delivery 

DHL’s Electronic Proof of Delivery lets you get delivery details and an image of the receiver’s signature, if it is captured digitally. When a shipment is delivered by DHL, the recipient signs and writes their name on the driver’s hand-held device. The digital signature is available the next day after delivery.

Some ordering clients want Proof of Delivery, because they want to charge their customers. 

The API can provide users with a Proof of Delivery.

The API will also identify the DPDHL service provider involved.

 

Get information on shipment delays

Some customers want to be informed of any potential delays to a delivery.

The API can provide them with the information regarding potential shipment delays.

The API will also identify the DPDHL service provider involved.

 

Customize my web application

You can use optional parameters and customize your web application based on your users’ needs. 

You can use the API to create language-specific web applications, so that customers can track their shipment in their native language.

 

 

User Guide

Get Access

You must request credentials for any applications you develop

To register your app and get your API subscription keys:

  1. Click My Apps on the portal website.
  2. Click the + Add App button.
    The “Add App” form appears.
  3. Complete the Add App form. 
    You can select the APIs you want to access.
  4. When you have completed the form, click the Add App button.

 

Authentication

Every call to the API requires a subscription key. This key needs to be passed through a request header (DHL-API-Key).

To view your API subscription keys:

  1. From the My Apps screen, click on the name of your app.
    The Details screen appears. 
  2. If you have access to more than one API, click the name of the relevant API. 
    Note: The APIs are listed under the “Credentials” section. 
  3. Click the Show link below the asterisks that is hiding the Consumer Key
    The Consumer Key appears.    

 

Environments

The addressable API base URL/URI environments are:  

Environment Description
https://api-eu.dhl.com/track/shipments Sandbox and production environment

 

Rate limits

Rate limits protect the DHL infrastructure from suspicious requests that exceed defined thresholds.

When you first request access to the Shipment Tracking - Unified API, you will get the initial service level which allows 250 calls per day with a maximum of 1 call per second.

Additional rate limits are available and they are granted according to your specific use case. If you would like to request for additional limits, please proceed with the following steps:

  1. Create an app as described under Get Access section. 
  2. Click My Apps on the portal website.
  3. Click on the App you created
  4. Scroll down to the APIs list and click on the "Request Upgrade" button.
  5. Please refer to the example below:
Tracking API Request Upgrade Option

 

If the limit is reached, you will receive an HTTP Status code: 

429: Too many requests.  

 

Additional Information

 

Message Format

This API uses RESTful JSON format to represent any resource affordances and link relations between resources. Any non-error response of application/json media type shall be interpreted as defined in RESTful JSON specification.

 
JSON-LD

Furthermore, the RESTful JSON responses are in JSON-LD-compatible format.

 
General conventions

Enums defined in the API response entities might hold just a subset of possible values (e.g. new values can be added to enum in future non-breaking versions). In the case, when the value doesn’t meet clients expectation, client should process it as undefined.

 
Error Message Format

In the case of error, the application/problem+json (Problem Detail) is used to communicate details about an error.

 
Date & Time format

Date and Time always conform to the ISO 8601 format e.g.: 2017-06-21T14:07:17+2:00 (date time) or 2017-06-21T14:07:17Z (date time) or 2017-06-21 (date). If no time zone information is provided the time zone should be interpreted as in the place of the respective shipment event.

 

Error Responses

This API might use the full range of common HTTP response statuses as defined in RFC7231.
This API documentation shows only the 404 for illustration purposes on how an error response might look like.

 

Language

The API request might return localized messages (e.g. human readable description of a shipment status code). It is possible to indicate the language preferred by the calling user agent using the language query parameter. If the requested language is not available but the shipment is still found the API returns a successful response and indicates the actual langaguage of the response in the Content-Language header.

 
API Client Recommendation

Clients of the API should expect, that enums defined in the API response entities might hold just subset of possible values (e.g. new values can be added to enum in future non-breaking versions). In the case, when the value doesn’t meet clients expectation, client should process it as undefined.
Clients are advised, that optional fields may not be included in response when their value is not defined.

 
Selecting the preferred language

The API request can return localized messages (e.g. a human readable description of a shipment status code). 

To select your preferred language:

  • Use the language query parameter when calling the user agent.

If the requested language is not available but the shipment is still found, the API returns a successful response and indicates the actual language of the response in the Content-Language header.

 

Permitted HTTP methods
HTTP method Use this to:
GET

Retrieve data

 

DHL Parcel queries and responses

DHL Parcel Germany

For our parcel services in Germany, you can add recipientPostalCode to your query. This will provide you with more detailed information about the shipment.

DHL Parcel Netherlands

For our parcel services in the Netherlands, you can add recipientPostalCode to your query. This will provide you with more detailed information, such as status information.

 

Example requests to the API

Simple HTTP request example

curl -X GET 'https://api-eu.dhl.com/track/shipments?trackingNumber=7777777770' -H 'DHL-API-Key:PasteHere_ConsumerKey'

 

An explanation of the simple HTTP request example

Command Description
curl

curl is the command for running the cURL tool from the command line interface. 

cURL is a tool for transferring data to or from a server that is on the internet.

-X

-X is the command that allows you to send the “HTTP method” that you want to use. 

HTTP methods are used by web browsers and web servers to request information from each other. The most common HTTP methods are GET, POST, PUT, and DELETE.

GET GET is the command (“HTTP method”) for requesting information from an API.
https://api-eu.dhl.com/track/shipments

https://api-eu.dhl.com/track/shipments is the endpoint location (URI) of the “resource” you are requesting. 

Resources are the information objects that the API can exchange. Resources have data associated with them.

? tells the API the request contains query string parameters. 

The ? followed by the parameters, and their values are called the “query string.” 

Parameters are options you can send with your requests. Parameters are used to tailor and filter the response you receive from the API.

In the query string, each parameter is listed one after the other, with an & separating them (not shown in this example). 

trackingNumber=7777777770 This query string requests information on a shipment whose tracking number is 7777777770. 
-H

-H is the command that allows you to pass “http request headers” to the API resource. 

Headers contain information about the request. It often contains security information, such as user authentication keys.
'DHL-API-Key: PasteHere_ConsumerKey'
An API subscription key is a long string of letters and numbers that is used to identify the person making the request to the API.  

You must replace PasteHere_ConsumerKey with the Consumer Key provided to you by DHL in the MyApps screen. 

 

Detailed HTTP request example

curl -X GET 'https://api-eu.dhl.com/track/shipments?trackingNumber=7777777770&service=express&originCountryCode=NZ&requesterCountryCode=GB' -H 'DHL-API-Key:PasteHere_ConsumerKey'

 

The cURL example contains these parameters:

Parameter Description Example

trackingNumber

The tracking number of the shipment for which you want tracking information. 7777777770

service

Advice on which service (provider) should be used to resolve the tracking number. express

originCountryCode

The country code of the shipment origin. This can be used to further qualify the
shipment tracking number (`trackingNumber`) parameter in the request.
NZ

requesterCountryCode

The requester country code. This can be used to adjust the display options. GB

 

Note: See the DHL Shipment Tracking API Reference Guide for more information on the available parameters.

 

Simple Python code sample

import http.client
import urllib.parse
import json

params = urllib.parse.urlencode({
    'trackingNumber': '7777777770',
    'service': 'express'
})

headers = {
    'Accept': 'application/json',
    'DHL-API-Key': 'ApiKeyHere'
}

connection = http.client.HTTPSConnection("api-eu.dhl.com")

connection.request("GET", "/track/shipments?" + params, "", headers)
response = connection.getresponse()

status = response.status
reason = response.reason
data = json.loads(response.read())

print("Status: {} and reason: {}".format(status, reason))
print(data)

connection.close()

 

 

Legal Terms
specifics for the use of Tracking Data
  • Data requested and received via the SHIPMENT TRACKING – UNIFIED API, such as transport status, estimated delivery time, including the tracking number is hereinafter referred to as “Tracking Data”.
  • Tracking Data is Confidential Information in the meaning of section “Communication” of the General Developer Portal Terms of Use. Other than set forth below You must not reveal and/or provide third parties with the Tracking Data and/or analyze, modify such data in any form and/or derive data/information especially for competitive purposes from it without DP DHL’s prior written consent.
  • Tracking Data is provided to You and/or the entity you are authorized to represent (hereinafter “You”/”Your”) via this SHIPMENT TRACKING – UNIFIED API under the prerequisite, that You retrieved the according tracking number in compliance with the applicable law, especially in the field of data protection and competition law and that You use the Tracking Data solely for Your own or Your customers’ legitimate tracking purposes.
  • You shall not combine Tracking Data with advertisement or present it in a way that it could be regarded as advertisement.
  • Unless otherwise agreed, You shall delete the Tracking Data 30 days after the delivery (of the shipment) to the recipient is completed.
  • Tracking Data shall be used in accordance with the following specification:
    • Display “Delivered by Deutsche Post DHL Group“ in text (minimum font size) as soon as it is presented/submitted to recipient and/or Your customers.
  • The use and submission of Tracking Data – including submission to any of Your subcontractors – shall always be in compliance with applicable laws and regulations, including – without limitation – data protection laws and competition/antitrust law.
  • If You are neither the sender nor the recipient of DP DHL Group-shipment/s, the Tracking Data refers to,
    • You shall ensure, that you are authorized to act on behalf of the sender and/or the recipient;
    • You shall make the sender and/or the recipient aware of the restrictions set out in this User Guide just as the General Developer Portal Terms of Use;
    • You shall make the sender aware of the necessity to inform the recipient transparently about the processing of his/her personal data according to applicable data protection laws;
    • You shall inform the sender and/or recipient transparently that the use of Your Application may result in the disclosure of data being subject to postal secrecy and data protection laws to third parties (including You).
status.csv TEXT/CSV - 86.91 KB
Disclaimer
03.Jun.2022

This changelog section is an abstract and optional representation of the actual changes to the API description. For full details of the changes to a previous version please refer to API description.

EDD for Parcel_de
01.Jul.2024

EDD (Estimate Date of Delivery) including time window has been enabled for parcel_de shipments.

eCommerce Status Code
02.May.2024
  • Under "status" you will now receive ecommerce codes e.g. “600”
  • The current content of "status" is moved to "description"
  • Secondary event description is mapped to status "remark"
Parcel DE Shipments Status Update
29.Apr.2024
  • Under "status" you will receive a set of codes e.g. “ZU”
  • The current content of "status" is moved to "remark"
  • "statusCode" and "description" remains unchanged
EDD eCommerce
04.Apr.2024
  • Expected Deliver date for service ecommerce is now visible in shipment.estimatedTimeOfDelivery if available
Parcel DE displaying cities after postal code has been added
03.Apr.2024
  • Service Parcel DE now shows city in addressLocality when correct recipientPostalCode is added in the request
Parcel PL and Parcel NL Status Update
28.Feb.2024
  • Added service Parcel NL "status" element to shipment.status.status and moved the current Parcel NL status to shipment.status.description
  • Added service Parcel PL "status" element to shipments.status.status
Express ProductCode and ProductName
27.Jan.2024

For Express ProductCode and ProductName details are now available

1.5.2
07.Dec.2023

Dynamic application security testing (DAST) is enabled. It helps to detect common security issues such as cross-site scripting (XSS), SQL injection, insecure direct object references, and more

1.5.1
27.Nov.2023

Added new 'destinationProvider' enum value 'poste-italiane'

1.5.2
10.Jan.2024

ERC major version 1.8.0 release

1.4.2
04.Oct.2023

'returnFlag' element is added in shipment body to mark the shipment as rejected or returned

Demo-key - usage change
27.Jun.2023

Effective June 27th, the functionality of the "Try Now" feature within the Unified Tracking API will be transitioned to provide mocked up responses for testing purposes instead of using real shipment data. This change also extends to the utilization of the demo key. Developers who currently employ the demo key are requested to complete a registration process in order to acquire their own unique API key.

1.4.1
14.Dec.2022

Updated service enum with value "ecommerce-europe'

1.3.2
01.Jun.2022
  • Added `provider` to shipment model, including the field `destinationProvider`.

1.3.1
08.Jul.2021
  • The tracking number example provided in the Open API Specification was updated
1.3.0
01.Jul.2021
  • Added `parcel-uk` to enum list `service`.
  • Added `pieceIds` to shipment event model.
  • Updated Date & Time format comment section.
1.2.0
29.Jun.2021
  • Added `sameday` to enum list `service`.
1.1.0
31.Jul.2020
  • Added `post-de` to enum list `service`.
1.0.13
31.Jul.2020
  • Updated to OpenAPI specification version 3.
  • Added `serviceUrl` and `rerouteUrl` to shipment model.
  • Added `reference` as new reference type in shipment details model.
  • Updated Description for statusCode
     
1.0.12
31.Jul.2020
  • Fixed typos, maintenance release.
1.0.11
31.Jul.2020
  • Added `shipment-id` to list of possible responses.
1.0.10
31.Jul.2020
  • Added pagination.
1.0.9
31.Jul.2020
  • Maintenance release
Upcoming Changes
20.Jul.2020
  • Starting from 31 July 2020, latest, it will be possible for you to retrieve mail / letter tracking (belonging to the brand name Post & Parcel Germany) in addition with the Shipment Tracking – Unified API. More details can be checked here
1.0.8
12.Jun.2019
  • Updated vocabulary location.
  • Added general conventions notice in comment section.
  • Added `housebill` to list of possible responses. 
1.0.7
13.May.2019
  • Removed example for `trackingNumber` and `recipientPostalCode`.
  • Modified format of the API description comment section.
Content review
15.Mar.2019
  • Added `Legal specifics for the use of tracking data` 
  • Adjusted the Standard `Rate Limits` 
1.0.6
27.Feb.2019
  • Minor typo fixes in comment section.
  • Edited description of requesterCountryCode.
1.0.5
26.Feb.2019
  • Fixed the host name introduced as part of the 1.0.4 version.
1.0.4
15.Feb.2019
  • Introduced new host name and API key header name. The old names are deprecated but still functional until further notice. Please migrate to the new host and API key header and refrain from using the deprecated ones.
  • Added a disclaimer in the changelog section.
  • Improved timestamps descriptions to convey the value might be either ISO 8601 date OR ISO 8601 date time.
  • Shipments:
    • Added description to the additional matching shipments link relation (`possibleAdditionalShipmentsUrl`) at the shipments level.
1.0.3
14.Dec.2018
  • Minor discription fixing of the fields`requesterCountryCode`, `originCountryCode`, `recipientPostalCode` and `language`.
  • Added `estimatedTimeOfDeliveryRemark` field to the response "Shipment" model.
  • Added various examples.
  • Added `documentURL` and marked `signatureURL` as deprecated to the response "ProofOfDelivery" model.
  • Added `possibleAdditionalShipmentsUrl` to reflect matches in other backends / services to the response "Shipment" model.
  • Fixed some warnings related to JSON syntax.
1.0.1
01.Oct.2018
  • Initial launch
Express - sorting event history
01.Feb.2024

improvement on sorting express checkpoints in the event history