USPS Tracking API Scraper — Bulk USPS Package Tracking & Delivery Status

Track thousands of USPS tracking numbers in a single run. Get real-time delivery status, timestamps, and full checkpoint scan history — no USPS Web Tools API key, no rate-limit headaches.

---

What is the USPS Tracking API Scraper?

The USPS Tracking API Scraper is a high-throughput Actor that pulls live package tracking data straight from USPS — at scale. It's built for e-commerce operators, 3PL and logistics platforms, and customer support teams who need to check delivery status for hundreds or thousands of shipments at once without babysitting the official USPS tracking page one number at a time.

It's built to be fast and cheap on Apify Compute Units (CUs), and easy to run on a schedule.

Try it now: paste in a list of tracking numbers (or upload a CSV/JSON array) and get structured, ready-to-use delivery data back in seconds.

---

What data can this Actor extract?

For every tracking number, the Actor returns:

• 📦 Current delivery status — Delivered, In Transit, Out for Delivery, Pre-Shipment, or Alert
• 🕒 Full checkpoint / scan history — every facility scan, sort, arrival, and departure event with timestamp and location
• 📍 Destination and last-known location
• 🚚 Delivery date and time once a package is delivered
• 🧾 Raw carrier response (optional), for audit trails or debugging

All statuses are normalized into a small, predictable set of values so you never have to parse messy carrier text in your own code.

---

Who uses a USPS tracking scraper like this?

• Online stores that want to show live shipping status on an order-status page without manually checking USPS.com
• 3PLs and fulfillment centers monitoring outbound shipment health across thousands of packages a day
• Customer support teams who need instant "where's my package" answers without switching tools
• Marketplace and dropshipping sellers reconciling delivery confirmations against orders
• Developers building a lightweight internal tracking dashboard who don't want to manage USPS Web Tools API credentials themselves

---

Key Capabilities

• ⚡ Bulk multi-tracking — batches tracking numbers together to cut network overhead and total run time
• 📜 Full checkpoint history — the complete chronological event log per package, not just the latest status
• 🏷️ Normalized status categories (DELIVERED, IN_TRANSIT, OUT_FOR_DELIVERY, PRE_SHIPMENT, ALERT) for simple downstream logic
• 💸 Low compute consumption — cheap to run at volume, even on large batches
• 🔁 Resilient execution — automatic retries with exponential backoff on transient network errors
• 🌐 Proxy-ready — optional Apify Datacenter/Residential proxy support for high-volume jobs

---

How to track USPS packages in bulk (quick start)

1. Open the Actor on Apify Store and click Try for free.
2. Paste your tracking numbers — as a JSON array, multiline text, or via the API — into the trackingNumbers field.
3. (Optional) Tune throughput — adjust batchSize and delayMs if you're running very large batches.
4. Run the Actor. Results stream to the dataset as each package is processed, so you don't have to wait for the full batch to finish to see data.
5. Export or pull results as JSON/CSV, or fetch them programmatically via the Apify API (see below).
6. Automate it — pair with Apify Schedules to re-check tracking numbers daily, or Apify Webhooks to notify Slack/your backend the moment a package is marked delivered.

---

Input Parameters

The Actor accepts input via the Apify Console interface or as a JSON payload via the API:

{
  "trackingNumbers": [
    "9400100000000000000000",
    "9205500000000000000000"
  ],
  "batchSize": 5,
  "delayMs": 500,
  "maxRetries": 3
}

Parameter	Type	Default	Description
trackingNumbers	Array of Strings	(Required)	List of USPS tracking numbers to query. Accepts strings, arrays, or multiline text.
batchSize	Integer	5	Number of tracking numbers processed per network request (range: 1–35). Recommended: 5–10.
delayMs	Integer	500	Inter-request pause in milliseconds to maintain smooth throughput.
maxRetries	Integer	3	Maximum retry attempts per request upon temporary network failure.
saveRawResponse	Boolean	false	When set to true, includes the raw response payload in the dataset record for auditing.
proxyConfiguration	Object	null	Apify proxy configuration for custom IP routing.

---

Output Data Structure

Results are streamed directly to the default dataset as records are processed. Each record looks like this:

{
  "trackingNumber": "9400100000000000000000",
  "status": "Delivered, In/At Mailbox",
  "statusCategory": "DELIVERED",
  "bannerNotice": "Your item was delivered in or at the mailbox at 11:52 am in STREAMWOOD, IL 60107.",
  "deliveryDate": "August 24, 2026 11:52 AM",
  "location": "STREAMWOOD, IL 60107",
  "latestActivity": {
    "status": "Delivered",
    "date": "August 24, 2026 11:52 AM",
    "location": "STREAMWOOD, IL 60107"
  },
  "scanHistory": [
    { "status": "Delivered", "date": "August 24, 2026 11:52 AM", "location": "STREAMWOOD, IL 60107" },
    { "status": "Out for Delivery", "date": "August 24, 2026 6:41 AM", "location": "STREAMWOOD, IL 60107" },
    { "status": "Arrived at Post Office", "date": "August 24, 2026 6:30 AM", "location": "HANOVER PARK, IL 60133" },
    { "status": "Accepted at USPS Facility", "date": "August 24, 2026 5:30 AM", "location": "HANOVER PARK, IL 60133" }
  ],
  "scrapedSuccessfully": true
}

---

Programmatic Usage

Python

from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
client = ApifyClient("<YOUR_API_TOKEN>")

run_input = {
    "trackingNumbers": [
        "9400100000000000000000",
        "9205500000000000000000"
    ],
    "batchSize": 5,
    "delayMs": 500
}

run = client.actor("anshumali/usps-tracking-scraper").call(run_input=run_input)

print(f"Check your data here: https://console.apify.com/storage/datasets/{run['defaultDatasetId']}")
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# Docs: https://docs.apify.com/api/client/python/docs/quick-start

Node.js

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: '<YOUR_API_TOKEN>' });

const runInput = {
    trackingNumbers: [
        '9400100000000000000000',
        '9205500000000000000000'
    ],
    batchSize: 5,
    delayMs: 500
};

const run = await client.actor('anshumali/usps-tracking-scraper').call(runInput);
const { items } = await client.dataset(run.defaultDatasetId).listItems();

items.forEach(item => console.log(item));

---

Why run this on Apify instead of building it yourself?

• No infrastructure to manage — runs on Apify's cloud, scales to your batch size automatically
• API-first — trigger runs, fetch results, and integrate via the Apify API or client SDKs
• Scheduling built in — check tracking numbers on a recurring schedule with zero extra code
• Webhook integrations — connect to Slack, Make, Zapier, or n8n the moment a package's status changes
• Proxy rotation available — for sustained high-volume tracking without interruptions

---

FAQ

Do I need a USPS Web Tools API key to use this? No. The Actor handles data retrieval for you — just supply tracking numbers and run it.

How many tracking numbers can I check in one run? There's no hard cap — the Actor is built for bulk use. For very large batches (5,000+ numbers/day), Residential Proxies are recommended for sustained reliability.

What tracking number formats are supported? Standard USPS tracking numbers (typically 20–22 digits), including Priority Mail, First-Class Package, and Certified Mail formats.

Can I get notified automatically when a package is delivered? Yes — pair the Actor with Apify Webhooks or a schedule to poll tracking numbers and trigger an alert on status change.

How is this different from checking USPS.com manually? This Actor is built for bulk and automation — structured JSON output, scheduling, and API access — rather than checking one tracking number at a time in a browser.

Is the output data structured and consistent across carriers/services? Yes — every record is normalized into the same schema regardless of the shipping service used (Priority, First-Class, Certified, etc.), so your downstream code doesn't need carrier-specific parsing.

---

Operational Recommendations

1. Throughput tuning — for jobs under 1,000 numbers, the defaults (batchSize: 5, delayMs: 500) work well out of the box.
2. Proxy selection — for scheduled or continuous tracking exceeding 5,000 packages/day, configure Apify Residential Proxies for sustained uptime.
3. Webhook integration — pair with Apify Webhooks to notify your backend or automation platform (Make, Zapier, n8n) the moment a batch completes.

---

Support and Inquiries

For technical assistance, bug reports, or feature requests, open an issue in the associated repository or submit a ticket via the Apify Console.