A Python tracking integration needs to handle more than a successful JSON response. A carrier can be temporarily unavailable, a scan can have no timezone, and a retry can outlive the request that started it. Treat those as explicit outcomes rather than converting them into a pending shipment.
Trace provides a versioned Python client for Python 3.11 or newer. Its downloadable wheel is the supported installation path; do not assume a similarly named package on PyPI is this SDK.
Install the pinned server-side client
Install the versioned wheel below in a virtual environment and supply TRACE_API_KEY through your server environment. Pin the artifact in your dependency configuration so a deploy does not silently change its contract. The key belongs on your server, never in a browser response or notebook shared publicly.
Python 3.11+ · installation
pip install https://traceapi.dev/downloads/traceapi_sdk-0.3.0-py3-none-any.whlHandle a real lookup without hiding the failure
Set TRACKING_NUMBER to an authorized parcel with known scans. A supplied carrier code is useful when fulfillment data already identifies the carrier. The example prints only status and verification time, avoiding the customer timeline in routine logs. HTTP 503 means the lookup could not obtain usable source evidence; it does not establish that the parcel is lost.
Python · run on the server
import os
from traceapi import Trace, TraceError
trace = Trace(os.environ["TRACE_API_KEY"], timeout=95, retries=0)
try:
result = trace.track(os.environ["TRACKING_NUMBER"])
print(result["status"], result.get("last_checked_at"))
except TraceError as error:
print("Lookup unavailable", error.status, error.code, error.request_id)
raise
# Transport failures also propagate; the caller decides when to retry.Give the caller an explicit time and usage budget
The SDK defaults to a 95-second timeout per attempt and up to two retries on supported HTTP 429/503 failures. Those attempts and any retry delay can exceed a short web request deadline. Setting retries=0, as above, makes an outer worker responsible for scheduling another attempt. Do not retry in both layers without a shared deadline.
Successful live, cached and explicitly requested stale results consume monthly quota. Failed lookups and sandbox scenarios do not. Free accounts start with 200 monthly lookups at 10 requests per minute; the rate limit still applies to sandbox calls.
Test response semantics before exposing them to a buyer
Use trace.sandbox("unknown_timezone") to exercise null UTC timestamps, then test delivered and exception fixtures separately. Keep source-local time as text when its offset is unknown. A successful fixture tests your parser and UI, not live carrier availability.
- Assert that a source error never becomes a delivered or pending success in your application.
- Ensure missing estimated delivery stays absent instead of defaulting to today.
- Test a timeout separately from an HTTP rejection, and avoid logging the API key.
- Check a real authorized parcel after the sandbox passes; record the verification time.
Common questions
Is the Python SDK available on PyPI?
Use the pinned wheel linked above. The documented distribution is a hosted download; registry publication is not assumed.
References & next steps
Implementation details were checked against Trace’s current API. External product details may change; verify the linked documentation before deciding.