USPS Package Tracking Scraper

High-throughput bulk tracking scraper for the United States Postal Service. Extracts real-time package delivery status, timestamps, destination details, and full checkpoint scan history.

---

Overview

The USPS Package Tracking Scraper provides programmatic, scalable access to package tracking data directly from the United States Postal Service. Built specifically for e-commerce operators, logistics platforms, and customer operations teams, this Actor processes shipments in bulk with high throughput and predictable execution times.

By operating directly over an optimized network pipeline rather than running resource-heavy browser instances, the Actor achieves significant compute efficiency and reduces operational costs on the Apify platform.

---

Key Capabilities

• Bulk Multi-Tracking: Aggregates tracking numbers into structured batches, minimizing network overhead and significantly reducing total execution time.
• Full Checkpoint History: Extracts the complete chronological event log for every package, including facility arrivals, departures, sort facility scans, and delivery timestamps.
• Normalized Status Categorization: Standardizes carrier statuses into clear operational states (DELIVERED, IN_TRANSIT, OUT_FOR_DELIVERY, PRE_SHIPMENT, ALERT) for straightforward downstream logic.
• Low Compute Consumption: Lightweight execution profile that avoids headless browser overhead, consuming minimal Apify Compute Units (CUs).
• Resilient Execution: Integrated request management with exponential backoff handling transient network disruptions automatically.
• Proxy Compatibility: Supports optional integration with Apify Datacenter and Residential proxy pools for high-volume jobs.

---

Input Parameters

The Actor accepts input via the Apify Console interface or as JSON payload via 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 conforms to the following schema:

{
  "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
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "trackingNumbers": [
        "9400100000000000000000",
        "9205500000000000000000"
    ],
    "batchSize": 5,
    "delayMs": 500
}

# Run the Actor and wait for it to finish
run = client.actor("anshumali/usps-tracking-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
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)

# Documentation: 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);
});

---

Operational Recommendations

1. Throughput Tuning: For jobs under 1,000 numbers, the default setting (batchSize: 5, delayMs: 500) provides optimal performance.
2. Proxy Selection: For scheduled or continuous tracking operations exceeding 5,000 packages daily, configuring Apify Residential Proxies ensures sustained uptime.
3. Webhook Integration: Pair with Apify Webhooks to notify your backend or triggering platforms (Make, Zapier, n8n) the moment package batches complete.

---

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.