DHL APIdhl.com ↗
Track DHL shipments, find service points, get address suggestions, and retrieve service alerts via a single REST API. 8 endpoints, real tracking event data.
What is the DHL API?
This API exposes 8 endpoints covering DHL shipment tracking, service point discovery, address geocoding, and operational alerts. The track_shipment endpoint returns a full shipment object including status, a chronological event list, and delivery details. Separate endpoints let you isolate just the current status, the event history, or the estimated delivery timestamp — useful when you only need a single field rather than the full payload.
curl -X GET 'https://api.parse.bot/scraper/9d062457-066e-437e-ad7d-4979ace42d65/track_shipment?tracking_number=JJD014600007380167713' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace dhl-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
from parse_apis.dhl_logistics_api import DHL, Shipment, ServicePoint, AddressSuggestion, Country, Alert, ShipmentNotFound
dhl = DHL()
# Track a shipment by number
shipment = dhl.shipments.get(tracking_number="JJD014600007380167713")
print(shipment.tracking_number, shipment.status_)
# Get current status via constructible shipment
constructed = dhl.shipment("JJD014600007380167713")
status_info = constructed.status()
print(status_info.status, status_info.location, status_info.timestamp)
# Get delivery estimate
estimate = constructed.estimated_delivery()
print(estimate.estimated_delivery)
# Search for nearby service points
for point in dhl.servicepoints.search(address="10001", country_code="US"):
print(point.service_point_name, point.distance, point.facility_id)
# Get address suggestions
for suggestion in dhl.addresssuggestions.search(query="10001", country_code="US"):
print(suggestion.label, suggestion.value, suggestion.place_id)
# List available countries
for country in dhl.countries.list():
print(country.country_code, country.postcode, country.postcode_formats)
# Check service alerts
for alert in dhl.alerts.list():
print(alert.date, alert.title, alert.description)
Track a DHL shipment by tracking number. Returns the full shipment object including status, all tracking events, and delivery details when the shipment is found. Returns a not-found indicator with status Not Found when the tracking number has no associated shipment.
| Param | Type | Description |
|---|---|---|
| tracking_numberrequired | string | DHL tracking number (alphanumeric, typically 10-34 characters) |
{
"type": "object",
"fields": {
"detail": "string, description when shipment is not found",
"status": "string, current shipment status or Not Found",
"shipments": "array of shipment objects with status, events, and delivery info (present when shipment is found)",
"tracking_number": "string, the queried tracking number"
},
"sample": {
"data": {
"detail": "No shipment with given tracking number found.",
"status": "Not Found",
"tracking_number": "JJD014600007380167713"
},
"status": "success"
}
}About the DHL API
Shipment Tracking
The core tracking surface is split across four endpoints. track_shipment returns the complete shipment object when found — including a shipments array with status, events, and delivery info — or a detail string and status: 'Not Found' when the tracking number has no associated record. get_shipment_status trims the response to status, location (city of last known event), and an ISO timestamp. get_shipment_events returns only the ordered events array, each item containing timestamp, location, and description. get_estimated_delivery returns a single ISO-formatted estimated_delivery string, or null when no estimate is available. All four endpoints accept a tracking_number string, typically 10–34 alphanumeric characters.
Service Point Discovery and Address Handling
find_service_point accepts a freeform address string and an optional country_code (ISO 3166-1 alpha-2). It returns up to 10 nearby DHL Express drop-off/pickup locations, each with name, address, geoLocation, distance, openingHours, and capabilities fields, plus a searchLocation object showing the resolved coordinates and geocoded suggestion. If you need to validate or normalize an address first, get_address_suggestions takes a query string and optional country_code and returns candidate addresses with label, value, placeId, latitude, longitude, providerId, and countryCode fields. The value field is formatted for direct use as input to find_service_point.
Countries and Service Alerts
list_countries requires no inputs and returns every country where DHL shipping services are available. Each record includes countryCode, a postcode boolean, postcodeFormats (an array of valid format patterns), and recommendedPostcodeFormat when postcodes apply. get_service_alerts also requires no inputs and returns an alerts array of current disruption notices and operational information, each with date, title, and description.
The DHL API is a managed, monitored endpoint for dhl.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when dhl.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official dhl.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Display live parcel status and last-known city in an e-commerce order management dashboard using
get_shipment_status. - Send push notifications when a new event appears in the
eventsarray returned byget_shipment_events. - Surface estimated delivery dates in a checkout confirmation flow using
get_estimated_delivery. - Build a store-locator widget that finds the nearest DHL drop-off point from a user-entered postcode via
find_service_point. - Autocomplete and validate shipping addresses before checkout using
get_address_suggestions. - Populate a country selector filtered to DHL-supported markets using
list_countries, respecting validpostcodeFormats. - Monitor DHL service disruptions and display relevant alerts to customers using
get_service_alerts.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does DHL have an official developer API?+
What does `track_shipment` return differently from `get_shipment_status`?+
track_shipment returns the full shipments array with complete event history and delivery details, plus a detail string when the number is not found. get_shipment_status returns only three fields — status, location, and timestamp — covering just the most recent state. Use track_shipment when you need the full record; use get_shipment_status for lightweight polling.Does the API support tracking shipments from DHL eCommerce or DHL Parcel (non-Express services)?+
Can I retrieve a full shipment history for multiple tracking numbers in one call?+
tracking_number per request. Batch tracking across multiple numbers in one call is not currently supported. You can fork the API on Parse and revise it to add a batch endpoint that fans out calls and aggregates the results.What happens when `get_estimated_delivery` returns null?+
estimated_delivery means DHL has not published an estimated or actual delivery timestamp for that shipment yet. This is common for shipments that were just created, are held in customs, or where the service type does not include a delivery commitment.