USPS Package Tracking Scraper avatar

USPS Package Tracking Scraper

Pricing

from $3.00 / 1,000 tracked packages

Go to Apify Store
USPS Package Tracking Scraper

USPS Package Tracking Scraper

Track hundreds of USPS packages in one run. Get delivery status, timestamps, locations, and full scan history as structured JSON—fast, reliable, and built for e-commerce and logistics teams tracking at scale.

Pricing

from $3.00 / 1,000 tracked packages

Rating

0.0

(0)

Developer

Ansh K

Ansh K

Maintained by Community

Actor stats

0

Bookmarked

43

Total users

22

Monthly active users

a day ago

Last modified

Categories

Features

Limited permissions

Share

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, dependable, and cost-effective with Pay-Per-Event (PPE) pricing:

Fair Billing Guarantee: You are only charged for successfully tracked packages. Failed, blocked or unprocessed lookups are free.

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.


Pricing & Fair Billing Policy

This Actor uses pay-per-event pricing ($0.003 per successfully tracked package):

  • Success: Only records where real tracking information is parsed (scrapedSuccessfully: true) trigger the billable event.
  • Failures & Timeouts: If a request is blocked, times out, or encounters carrier errors, it is saved in your dataset with scrapedSuccessfully: false and an error description — completely free of charge.
  • Not Found: Genuine USPS "not found" / un-scanned items are returned as free records.
  • Charge Limit Safety: If your account or task hits a configured spending limit, the Actor immediately halts new requests, saves remaining numbers as NOT_PROCESSED (free), and writes a re-run list to the OUTPUT store.
  • Idempotent Billing: In the event of a platform migration or restart, previously tracked and charged numbers are skipped and never billed twice.

Key Capabilities

  • ⚡ Bulk multi-tracking — batches tracking numbers together to cut network overhead and total run time
  • 🛡️ Adaptive Pacing (AIMD) — automatically tunes batch sizes and delays in response to network conditions
  • 📜 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
  • 💸 Fair pay-per-event pricing — only pay for successful lookups; failures and blocked queries are free
  • 🔁 Resilient execution — automatic retries with fresh proxy sessions per attempt and hard request timeouts
  • 🌐 US Residential Proxy default — configured by default for maximum carrier unblocking and zero Akamai challenges

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 — defaults are batchSize: 10 and delayMs: 3000 with US Residential proxies.
  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": 10,
"delayMs": 3000,
"maxRetries": 5
}
ParameterTypeDefaultDescription
trackingNumbersArray of Strings(Required)List of USPS tracking numbers to query. Accepts strings, arrays, or multiline text. You are only charged for successfully tracked packages. Failed, blocked or unprocessed lookups are free.
batchSizeInteger10Number of tracking numbers combined in each batch. Defaults to 10 for maximum reliability. Range: 1–35.
delayMsInteger3000Inter-request pause in milliseconds between batches. The Actor automatically adjusts pacing if rate limits are encountered.
maxRetriesInteger5Maximum retry attempts per request upon temporary network failure. Each retry uses a fresh proxy session.
saveRawResponseBooleanfalseWhen set to true, includes the raw response payload in the dataset record for auditing.
proxyConfigurationObjectUS ResidentialApify proxy configuration. US Residential proxy is enabled by default to prevent carrier blocks.

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,
"errorMessage": null
}

If a tracking number fails, it is saved with full details so you know what happened:

{
"trackingNumber": "9400100000000000000001",
"status": "ERROR",
"statusCategory": "ERROR",
"deliveryDate": "",
"location": "",
"latestActivity": {},
"scanHistory": [],
"scrapedSuccessfully": false,
"errorMessage": "Failed after 3 attempts: Request timed out"
}

Integration Guide & Sample Code

You can easily integrate this Actor into your e-commerce platforms, order management systems (OMS), logistics pipelines, or customer support dashboards using the Apify API and official SDKs.

1. Python Integration (Backend / Microservices)

Install the official Apify Python SDK:

$pip install apify-client
import os
from apify_client import ApifyClient
# Initialize client with your Apify API token (set via environment variable or string)
client = ApifyClient(os.getenv("APIFY_TOKEN", "<YOUR_API_TOKEN>"))
def track_packages(tracking_numbers: list[str]) -> list[dict]:
"""
Submits tracking numbers to the Actor and returns structured status records.
"""
run_input = {
"trackingNumbers": tracking_numbers,
"batchSize": 10,
"delayMs": 3000,
}
# Start the Actor and wait for completion
run = client.actor("anshumali/usps-tracking-scraper").call(run_input=run_input)
# Fetch and return the results from the default dataset
dataset_items = list(client.dataset(run["defaultDatasetId"]).iterate_items())
return dataset_items
if __name__ == "__main__":
# Example: Track multiple packages in bulk
numbers_to_check = [
"9400100000000000000000",
"9205500000000000000000"
]
results = track_packages(numbers_to_check)
for pkg in results:
print(f"[{pkg['trackingNumber']}] {pkg['status']} | Category: {pkg['statusCategory']} | Delivered: {pkg['deliveryDate']}")

2. Node.js & TypeScript Integration (Express, Next.js, NestJS)

Install the official Apify JavaScript SDK:

$npm install apify-client
import { ApifyClient } from 'apify-client';
const client = new ApifyClient({
token: process.env.APIFY_TOKEN || '<YOUR_API_TOKEN>',
});
interface TrackingRecord {
trackingNumber: string;
status: string;
statusCategory: string;
deliveryDate?: string;
location?: string;
latestActivity?: {
date?: string;
status?: string;
location?: string;
};
scanHistory?: Array<{
date: string;
status: string;
location: string;
}>;
scrapedSuccessfully: boolean;
errorMessage?: string | null;
}
export async function trackShipments(trackingNumbers: string[]): Promise<TrackingRecord[]> {
const runInput = {
trackingNumbers,
batchSize: 10,
delayMs: 3000,
};
// Run the actor and wait for it to finish
const run = await client.actor('anshumali/usps-tracking-scraper').call(runInput);
// Retrieve dataset items
const { items } = await client.dataset(run.defaultDatasetId).listItems();
return items as unknown as TrackingRecord[];
}
// Example usage
async function main() {
const shipments = await trackShipments([
'9400100000000000000000',
'9205500000000000000000',
]);
for (const s of shipments) {
console.log(`${s.trackingNumber}: ${s.statusCategory} - ${s.status} (Delivered: ${s.deliveryDate || 'N/A'})`);
}
}
main().catch(console.error);

3. Direct REST API / cURL (Synchronous Single-Call Integration)

If you don't want to install an SDK or want to integrate with any programming language (PHP, Go, Ruby, C#, Java) or no-code automation platforms (n8n, Make, Zapier), use the synchronous run-sync-get-dataset-items endpoint. It runs the Actor and directly returns the JSON array of tracking records:

curl -X POST "https://api.apify.com/v2/acts/anshumali~usps-tracking-scraper/run-sync-get-dataset-items?token=<YOUR_API_TOKEN>" \
-H "Content-Type: application/json" \
-d '{
"trackingNumbers": [
"9400100000000000000000",
"9205500000000000000000"
],
"batchSize": 10,
"delayMs": 3000
}'

4. Asynchronous Webhook Integration (High-Volume Pipelines)

For large daily batches (e.g. 1,000+ packages), start the Actor asynchronously with an event webhook so your backend receives the data automatically as soon as scraping completes:

import os
from apify_client import ApifyClient
client = ApifyClient(os.getenv("APIFY_TOKEN"))
# Start Actor asynchronously and configure a webhook
run = client.actor("anshumali/usps-tracking-scraper").start(
run_input={
"trackingNumbers": ["9400100000000000000000", "9205500000000000000000"],
"batchSize": 10,
"delayMs": 3000
},
webhooks=[
{
"eventTypes": ["ACTOR.RUN.SUCCEEDED"],
"requestUrl": "https://api.yourdomain.com/webhooks/tracking-completed",
"payloadTemplate": "{\"runId\": {{eventData.actorRunId}}, \"datasetId\": {{eventData.defaultDatasetId}}}"
}
]
)
print(f"Actor run initiated: {run['id']}. Webhook will be triggered upon completion.")

High-Volume Recommendations & Sizing

For processing hundreds to tens of thousands of packages:

  1. Recommended Memory: Set Actor memory to 1024 MB (1 GB). This provides optimal networking and buffer space without excess compute costs.
  2. Run Timeout Budget: Configure run timeout with at least (N / 1 per second) * 1.20 margin. For example:
    • 500 numbers: ~10–12 minutes
    • 1,500 numbers: ~25–30 minutes
    • 3,000 numbers: ~60 minutes (1 hour)
  3. Resumability & Automatic Checkpointing: Progress is persisted on every batch. If a run is migrated by Apify or reaches a timeout deadline, it stops cleanly without losing records. Restarting the run skips already-processed numbers and never charges for them again.
  4. Automated Recovery on Blocks: When carrier rate limits or blocks occur (>30% failure rate over 50 requests), the Actor pauses for 30–120s with jitter, rotates residential proxy sessions, halves batch size, and doubles delays to continue without aborting.
  5. Slow Re-queue Pass: Failed tracking numbers are automatically re-queued once at the end of the run using single-item requests and maximum delays before finally being categorized as errors.
  6. Guaranteed 1-to-1 Input-to-Dataset Reconciliation: Every single input tracking number is guaranteed exactly one record in the output dataset. Attempted failures include real error diagnostic reasons (errorMessage), and unattempted numbers are marked as NOT_PROCESSED.
  7. Attempted-Only Success Rate: The success rate is computed strictly against attempted packages (succeeded / (succeeded + failed)), ensuring unattempted numbers do not artificially depress your reliability metrics.
  8. Key-Value Store Output: Check the Key-Value Store record OUTPUT for lightweight run summaries, status metrics, and a sample of failed numbers without exceeding storage limits.

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.