API Documentation

Predict delivery time windows for German e-commerce with a single API call.

Authentication

All API requests require a Bearer token. Create an API key in your dashboard, then pass it in the Authorization header.

Authorization: Bearer km_live_your_api_key_here

POST /v1/predict

Returns a predicted delivery time window for a carrier and German postal code (PLZ).

Request

curl -X POST https://api.kommt.dev/v1/predict \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "carrier": "dhl",
    "postal_code": "10115"
  }'

Field	Type	Description
carrier	string	Carrier code (see list below)
postal_code	string	5-digit German PLZ

Response

{
  "carrier": "dhl",
  "postal_code": "10115",
  "predicted_date": "2026-03-20",
  "window": {
    "start": "09:00",
    "end": "14:00"
  },
  "confidence": 0.82,
  "based_on": 347,
  "scope": "plz"
}

Response Fields

Field	Description
predicted_date	Expected delivery date (YYYY-MM-DD, German timezone)
window	Delivery time window with `start` and `end` in HH:00 format (P10 and P90 of historical deliveries)
confidence	0.0 to 0.95 — higher with more data points. Reduced for region/national scope.
based_on	Number of historical delivery records used
scope	Data scope used: `plz` (exact match), `region` (3-digit PLZ prefix), or `national` (carrier average)

Supported Carriers

Code	Carrier
dhl	DHL
hermes	Hermes
dpd	DPD
gls	GLS
ups	UPS
amazon	Amazon Logistics

Rate Limits

Requests are tracked per calendar month (Berlin timezone).

Plan	Requests/month	Price
Free	500	EUR 0
Pro	25,000	EUR 49/mo
Scale	100,000	EUR 149/mo

Error Codes

Status	Code	Description
400	INVALID_INPUT	Invalid carrier or postal code format
401	UNAUTHORIZED	Missing or invalid API key
404	NOT_FOUND	No data available for this carrier (even nationally)
429	RATE_LIMIT_EXCEEDED	Monthly request limit reached