DHL Package Tracking Scraper

Track DHL packages by tracking number and return a compact, machine-readable record with the current status, latest checkpoint, estimated delivery, origin/destination, service, and event history. Use it for shipment visibility, customer-support workflows, logistics monitoring, and agent pipelines that need structured DHL tracking data.

What it extracts

Each matched shipment becomes one default-dataset item with:

Field	Description
trackingNumber, shipmentId	Requested ID and DHL's canonical shipment ID
status, statusCode, description, statusTimestamp	Current milestone and when DHL reported it
estimatedDelivery	DHL's ETA/date when available
currentLocation	Latest public checkpoint locality
origin*, destination*	Public country, postal code, and city fields
service, productName, totalPieces	DHL business unit/product and piece count
events	Normalized checkpoint history with timestamp, status, description, and location
serviceUrl, sourceUrl, retrievedAt	DHL links and retrieval provenance
isDemoData, raw	Demo marker and optional original shipment object

Protected recipient details may require recipientPostalCode. DHL may omit fields when a shipment or service does not expose them.

Input

trackingNumbers accepts one to ten DHL IDs. Spaces, commas, and semicolons are treated as separators, and IDs must contain only letters, numbers, or hyphens after normalization.

For real shipments, turn demoMode off. In auto mode, the Actor uses the official DHL Shipment Tracking - Unified API when dhlApiKey is supplied, otherwise it opens DHL's public tracking page in a consistent browser session. Set accessMode to api to require the API or website to require the public page.

The API route is the recommended production path. Request a Consumer Key for Shipment Tracking - Unified at developer.dhl.com, then paste it into the secret dhlApiKey input. The key is sent only in the DHL-API-Key header and is never written to logs, the dataset, or SUMMARY.

The default sample input uses DHL's documented sample ID 7777777770 with demoMode: true. DHL returns a mocked response for the special demo-key; this is intentionally labelled with isDemoData: true and must not be used as a real shipment lookup. demoMode rejects other tracking IDs so a forgotten demo setting cannot silently return unrelated data. The optional recipientPostalCode is ignored in demo mode because DHL's sample fixture does not model postal-code disambiguation; the Actor records that decision in SUMMARY.warnings.

Console example (real API)

{
  "trackingNumbers": ["00340434292135100186"],
  "demoMode": false,
  "accessMode": "api",
  "dhlApiKey": "your-consumer-key",
  "language": "en",
  "requesterCountryCode": "US",
  "includeRaw": false
}

API example

apify call YOUR_USERNAME/dhl-package-tracking-scraper \
  --input '{"trackingNumbers":["00340434292135100186"],"demoMode":false,"accessMode":"api","dhlApiKey":"..."}' \
  --wait

Do not put a DHL key in a URL or a public README. Use the secret input or an environment-managed run payload.

Output example

{
  "trackingNumber": "7777777770",
  "shipmentId": "00340434292135100186",
  "service": "ecommerce",
  "productName": "DHL SM Parcel Plus Expedited",
  "statusCode": "delivered",
  "status": "DELIVERED",
  "description": "DELIVERED - PARCEL LOCKER",
  "statusTimestamp": "2023-05-08T10:37:00",
  "estimatedDelivery": null,
  "originCountryCode": "US",
  "originCity": "HEBRON",
  "destinationCountryCode": "US",
  "destinationCity": "HENDERSON",
  "currentLocation": "Henderson, NV, US",
  "totalPieces": 1,
  "events": [],
  "isDemoData": true,
  "raw": null
}

The complete run summary is stored as SUMMARY in the default key-value store. It includes requested, delivered, empty, blocked, and failed counts, the access route, warnings, and expected synthetic dataset-item events. A successful data run writes one automatically billable apify-default-dataset-item event per delivered record; the Actor does not manually double-charge results.

Pricing and limits

Event	Price
Actor start	$0.00005 (synthetic)
Tracked DHL shipment	$0.02 per dataset record (synthetic)

Examples: one matched shipment costs up to $0.02005 in events; ten matched shipments cost up to $0.2005. Empty, blocked, rejected, and failed lookups write no result records and therefore incur no result event. Apify may also account for the platform resources selected for a run. The Actor processes at most ten tracking numbers and deliberately spaces multi-number API calls to respect DHL's initial one-call-per-five-seconds limit.

Reliability and failure behavior

The Actor uses DHL's first-party API when authorized, with bounded 30-second request timeouts and no fabricated records. Website mode uses a single consistent browser session and an Apify Proxy configuration by default; 403/428/429 responses and challenge pages are classified as blocked. A valid ID with no shipment is empty, malformed combinations are rejected, and upstream/runtime problems are failed. Partial valid results are preserved, and every skipped request is listed in SUMMARY.

Tracking events commonly appear 24–48 hours after DHL receives an ID. DHL's API and public tracking pages may limit destination or recipient information for privacy. A postal code can only be supplied for one shipment at a time in this Actor, matching DHL's protected-detail behavior.

Data-use note

Use tracking data only for legitimate shipment-tracking purposes and comply with DHL's developer terms, applicable privacy law, postal secrecy, and your data-retention obligations. Obtain any required sender/recipient consent. DHL's published Unified Tracking terms require appropriate attribution and may require deleting tracking data after delivery; review the current terms before redistributing results. Do not combine tracking data with advertising or use this Actor to bypass authentication, CAPTCHAs, paywalls, or other access controls.

Related use

This Actor tracks DHL IDs and returns shipment status. It does not create labels, calculate rates, download proof-of-delivery documents, or monitor push notifications. Use DHL's authorized APIs directly for those workflows.