DHL Package Tracking Scraper

Free-plan limit: Apify free-plan users receive at most 5 delivered shipment records per run. Paid and agentic-payment runs may process up to 10 tracking IDs.

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 and supply a DHL Shipment Tracking - Unified API key. auto and api both use the official API. Without a key, the Actor stops before opening a browser and explains how to proceed. The website option is temporarily disabled for live users. A Cheerio test through the configured DataImpulse proxy fetched the DHL tracking page and its page-owned endpoint, but DHL returned HTTP 428 (access challenge) with no shipment data. The owner can re-enable this route for a controlled retest if DHL access changes; it is not validated for real tracking.

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

Current Apify event prices and platform-usage treatment are listed in the dedicated Pricing section below.

At the current live prices, one matched shipment costs up to $0.02005 in Actor events; ten matched shipments cost up to $0.20005. Empty, blocked, rejected, and failed lookups write no result records and incur no result event, but the start event still applies. Apify platform usage for this Actor run is included in the event prices; no separate per-run platform-usage fee is charged. The API mode processes at most ten tracking numbers and deliberately spaces multi-number calls to respect DHL's initial one-call-per-five-seconds limit. Live website lookups are temporarily rejected before opening a browser, limiting cost while the access route is unavailable.

Reliability and failure behavior

The Actor uses DHL's first-party API when authorized, with bounded 30-second request timeouts and no fabricated records. The Cheerio website crawler is retained for controlled retests, but live website lookups currently return a clear rejected summary before any HTTP or proxy request. During the test it made at most two HTTP requests with no retry or session rotation, using the owner's DataImpulse proxy. External proxy invoices are separate from Apify usage. DHL 403/428/429 responses and challenge pages are classified as blocked; proxy tunnel failures are failed. A valid no-match DHL response is empty, malformed combinations are rejected, and malformed or timed-out upstream responses are failed. Partial valid results are preserved, and every skipped request is listed in SUMMARY. A working demo response does not prove that real tracking is available without a DHL API key.

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.

Pricing

This Actor uses pay-per-event pricing. These are the current Apify Store event prices:

Event	Price (USD)	When it is charged
apify-default-dataset-item	FREE: $0.02; BRONZE: $0.02; SILVER: $0.02; GOLD: $0.017; PLATINUM: $0.017; DIAMOND: $0.017	Tracked DHL shipment — One schema-valid DHL shipment record written to the default dataset.
apify-actor-start	$0.00005	Actor Start — Charged when the Actor starts running. Number of events charged depends on Actor memory (one event per GB, minimum one event). — Charged once per run.

Apify platform usage for this Actor run is included alongside the event prices above; no separate per-run platform-usage fee is passed to users.

The repository's .actor/pay_per_event.json contains a proposed, not yet live pricing update: a $0.005 start event on every tier and result events of $0.02 / $0.0195 / $0.019 / $0.016 for FREE / BRONZE / SILVER / GOLD and above. The current start fee is below the observed cost of a blocked website run. The owner must review this proposal in Apify Console; a public Actor's price increase may be scheduled after a notice period, so the live prices in the table above remain authoritative until Apify shows the new pricing as active.

This covers Apify platform usage for this Actor run. Other Apify products or usage outside this Actor run may still follow your account plan.