# USPS Tracking Scraper (`anshumali/usps-tracking-scraper`) Actor
Fast, reliable USPS package tracking scraper. Batch multiple tracking numbers in a single POST request with zero blocked requests. Extract delivery status, timestamps, locations, and full checkpoint history.
- **URL**: https://apify.com/anshumali/usps-tracking-scraper.md
- **Developed by:** [Ansh K](https://apify.com/anshumali) (community)
- **Categories:**
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet
## Pricing
from $1.00 / 1,000 tracked packages
This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event
## What's an Apify Actor?
Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".
## How to integrate an Actor?
If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.
- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).
For usage examples, see the [API](#api) section below.
For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).
# README
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:
```json
{
"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:
```json
{
"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
```python
from apify_client import ApifyClient
## Initialize the ApifyClient with your Apify API token
## Replace '' with your token.
client = ApifyClient("")
## 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
```javascript
import { ApifyClient } from 'apify-client';
const client = new ApifyClient({
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.
# Actor input Schema
## `trackingNumbers` (type: `array`):
List of USPS tracking numbers to scrape. Provide an array of tracking numbers.
## `batchSize` (type: `integer`):
Number of tracking numbers combined in a single comma-separated POST request. Recommended 1 to 10.
## `delayMs` (type: `integer`):
Delay in milliseconds between consecutive requests to avoid throttling.
## `maxRetries` (type: `integer`):
Maximum number of retries per request if temporary network or rate-limiting errors occur.
## `saveRawResponse` (type: `boolean`):
Include the raw response body in the scraped dataset for debugging or archival.
## `proxyConfiguration` (type: `object`):
Optional Apify Proxy configuration (residential or datacenter proxies).
## Actor input object example
```json
{
"batchSize": 5,
"delayMs": 500,
"maxRetries": 3,
"saveRawResponse": false
}
```
# Actor output Schema
## `results` (type: `string`):
Scraped tracking details including delivery status, timestamps, locations, and chronological scan event histories.
# API
You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.
## JavaScript example
```javascript
import { ApifyClient } from 'apify-client';
// Initialize the ApifyClient with your Apify API token
// Replace the '' with your token
const client = new ApifyClient({
token: '',
});
// Prepare Actor input
const input = {};
// Run the Actor and wait for it to finish
const run = await client.actor("anshumali/usps-tracking-scraper").call(input);
// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
console.dir(item);
});
// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs
```
## Python example
```python
from apify_client import ApifyClient
# Initialize the ApifyClient with your Apify API token
# Replace '' with your token.
client = ApifyClient("")
# Prepare the Actor input
run_input = {}
# 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.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
print(item)
# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start
```
## CLI example
```bash
echo '{}' |
apify call anshumali/usps-tracking-scraper --silent --output-dataset
```
## MCP server setup
```json
{
"mcpServers": {
"apify": {
"type": "http",
"url": "https://mcp.apify.com/?tools=fetch-actor-details,anshumali/usps-tracking-scraper"
}
}
}
```
The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer ` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).
## OpenAPI specification
Download the OpenAPI definition: https://api.apify.com/v2/actors/ejUdwzgGVbS472awS/builds/KCq9OwgkBvZZeOcxZ/openapi.json