# UPS Package Tracking Scraper (`parseforge/ups-package-tracking-scraper`) Actor

Track UPS packages in bulk from a list of tracking numbers. Returns current status, delivery timestamp, and complete scan event history for each shipment. Supports 1Z, Mail Innovations, FGV, and Freight formats.

- **URL**: https://apify.com/parseforge/ups-package-tracking-scraper.md
- **Developed by:** [ParseForge](https://apify.com/parseforge) (community)
- **Categories:** E-commerce, Automation
- **Features:** Limited permissions
- **Stats:** 63 total users, 14 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: 5.00 out of 5 stars

## Pricing

from $23.99 / 1,000 result items

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

[![ParseForge](https://raw.githubusercontent.com/ParseForge/apify-assets/main/banner-v4.webp)](https://apify.com/parseforge?fpr=vmoqkp)

### UPS Package Tracking Scraper

**Track UPS packages in bulk using only tracking numbers. Get status, delivery date, scan events, and package details for up to a million shipments per run.** No API account or login required. Export to CSV, JSON, Excel, or XML.

**Low minimum charge:** $0.005 to start a run, then you only pay for the results you get.

UPS tracking portals and official APIs require you to look up packages one by one or manage complex authentication. This Actor reads the public tracking feed directly from a list of tracking numbers, supporting standard 1Z, Mail Innovations, FGV, and Freight formats. It returns every package's current status, delivery timestamp, and full scan history in a single flat dataset.

| Who uses it | What they scrape UPS for |
|---|---|
| E-commerce operations managers | Monitor delivery performance across hundreds of daily outgoing orders. |
| Logistics coordinators | Verify bulk shipment statuses for freight and ground packages in one batch. |
| Customer support teams | Pull real-time tracking updates to answer customer delivery inquiries quickly. |
| Data analysts | Collect delivery timelines and scan events to measure carrier performance. |

### What it does

This Actor collects UPS package tracking data from a list of tracking numbers and returns each shipment's status, delivery details, and scan events as a structured row.

- 📦 **Bulk tracking:** Submit a list of tracking numbers and receive the current status for every package in a single run.
- 🌐 **Multi-locale support:** Request tracking responses in your local language and format, such as en_US, fr_FR, or de_DE.
- 📋 **Full scan history:** Each result includes the complete list of scan events with timestamps, locations, and descriptions.
- 🔢 **Flexible format support:** Works with standard 1Z tracking numbers, Mail Innovations identifiers, FGV codes, and Freight shipment IDs.

Results export to CSV, JSON, Excel, or XML, or straight from the API.

### What you can do with UPS data

**📊 Monitor daily order delivery status.**

An e-commerce operations manager uploads a CSV of outbound tracking numbers each morning to identify delayed shipments and update customers proactively.

**📦 Audit carrier performance over time.**

A logistics analyst scrapes scan event histories for thousands of delivered packages to calculate on-time delivery rates and flag recurring transit bottlenecks.

**💬 Power customer support with live tracking data.**

A support team integrates the Actor into their internal tool to pull the latest UPS status for any tracking number a customer inquires about.

**🌍 Localize tracking updates for international recipients.**

A global retailer sets the locale parameter to de_DE or fr_FR so tracking responses match the recipient's language and regional format.

### Why choose this scraper

|  | What you get |
|---|---|
| **Bulk processing** | Track thousands of packages in one run instead of checking them manually on the UPS website. |
| **No API key** | Access public tracking data without registering a UPS account or managing OAuth credentials. |
| **Structured output** | Receive clean, flat rows ready for spreadsheets, databases, or analytics tools. |
| **Multi-format input** | Mix standard 1Z codes with Mail Innovations, FGV, and Freight tracking numbers in the same request. |

### How it compares

No other Store actor targets UPS the same way, so the honest comparison is with the alternatives teams actually weigh.

| | UPS Package Tracking Scraper | Build it in-house | By hand |
|---|---|---|---|
| Setup | Run it now, zero config | Days of engineering | None, but hours per pull |
| When UPS changes | Maintained for you | You fix it | You re-learn the page |
| Proxies, retries, anti-bot | Built in | Your problem | Browser only |
| Output | Fixed JSON schema, CSV/Excel export | Whatever you build | Copy-paste |
| Cost | Pay per result | Engineering time | Analyst hours |

### Configure the run

Drive the Actor with a list of UPS tracking numbers and optionally set a locale for the response language. The maxItems limit controls how many packages are collected per run. The Input tab lists every parameter.

A first run with the defaults:

```json
{
  "trackingNumbers": [
    "1Z999AA10123456784"
  ],
  "maxItems": 10
}
```

A larger pull:

```json
{
  "trackingNumbers": [
    "1Z999AA10123456784"
  ],
  "maxItems": 200
}
```

### Pricing

Pay-per-result: **$0.03199 per result** collected. You pay only for the results written to your dataset.

| Results collected | Approximate cost |
|---|---|
| 100 results | $3.20 |
| 1,000 results | $31.99 |
| 10,000 results | $319.90 |

New Apify accounts start with $5 in free credit.

### Free users

Free-plan runs return up to 10 results as a preview. [Upgrade your Apify plan](https://console.apify.com/sign-up?fpr=vmoqkp) to collect up to 1,000,000 results per run.

### Run it

1. [Create a free Apify account with $5 in credit](https://console.apify.com/sign-up?fpr=vmoqkp).
2. Open the [UPS Package Tracking Scraper](https://apify.com/parseforge/ups-package-tracking-scraper?fpr=vmoqkp).
3. Set your inputs and any filters, then click **Start**.
4. Export the results as CSV, Excel, JSON, or XML from the **Dataset** tab.

Run it programmatically through the [Apify API](https://docs.apify.com/api/v2) (`run-sync-get-dataset-items`) or the [ApifyClient](https://docs.apify.com/api/client/js) for JavaScript and Python.

### Use with AI agents (MCP)

Give an AI agent live access to UPS through the Model Context Protocol. Add the Actor to Claude, Cursor, or any MCP client:

```bash
claude mcp add --transport http apify "https://mcp.apify.com?tools=parseforge/ups-package-tracking-scraper"
```

Then prompt it in plain language to run the scraper and read back the results.

### Troubleshooting

**Why am I getting no results for my tracking numbers?**

Check that your tracking numbers are valid and match a supported format like 1Z, Mail Innovations, FGV, or Freight. Also verify that the maxItems parameter is set high enough to include all your input numbers.

**The status shows 'Not Found' for a number I know is correct.**

UPS may not have scan data available yet for newly created labels. Wait a few hours and retry. If the issue persists, verify the number on the official UPS tracking website to confirm it is active.

**My run is taking too long with a large list of tracking numbers.**

The Actor processes numbers sequentially. For very large lists, consider splitting them across multiple runs or increasing the Actor's memory allocation in the run settings to improve throughput.

**The locale parameter is not changing the response language.**

Ensure you are using a valid locale code like en_US, fr_FR, or de_DE. Not all UPS tracking responses are fully localized for every language; some scan event descriptions may remain in English.

**I see a proxy or connection error during the run.**

This can happen if UPS temporarily blocks the request IP. The Actor uses Apify's proxy rotation. Retry the run, and consider enabling a longer timeout or using residential proxies if the problem repeats.

### FAQ

| Question | Answer |
|---|---|
| What tracking number formats does this Actor support? | It supports standard UPS 1Z tracking numbers, Mail Innovations identifiers, FGV codes, and Freight shipment IDs. You can mix different formats in the same input list. |
| Do I need a UPS account or API key to use this? | No. The Actor reads the public UPS tracking feed directly. You do not need to register an application, manage OAuth tokens, or sign up for a UPS API plan. |
| How many tracking numbers can I check in one run? | You can set the maxItems parameter up to 1,000,000 packages per run. The Actor processes the list sequentially and returns one row per tracking number. |
| What data does each result row contain? | Each row includes the tracking number, current package status, scheduled delivery date, actual delivery timestamp, and the full list of scan events with locations and descriptions. |
| Can I get tracking responses in languages other than English? | Yes. Set the locale parameter to a supported value like fr_FR, de_DE, or es_ES to receive status descriptions and scan event text in that language and regional format. |
| Does this Actor work for UPS Freight or Mail Innovations shipments? | Yes. The Actor accepts tracking numbers for UPS Freight, Mail Innovations, and other UPS service types alongside standard ground and air packages. |
| How do I export the tracking results? | You can export the dataset in CSV, JSON, Excel, or XML format directly from the Apify run console or via the API. |
| Is there a rate limit or will UPS block my requests? | The Actor reads public tracking pages at a controlled rate. For very large runs, the platform's proxy rotation helps distribute requests and reduce the chance of blocks. |
| Can I schedule this Actor to run automatically every day? | Yes. You can set up an Apify schedule to run the Actor daily with a fixed list of tracking numbers or feed it a dynamic list from an external API or data source. |
| What happens if a tracking number is invalid or not found? | The Actor returns a row for every input tracking number. If UPS reports the number as invalid or not found, the status field will reflect that error message from UPS. |

### Related actors

Browse the full [ParseForge collection](https://apify.com/parseforge?fpr=vmoqkp) for more scrapers.

🆘 **Need help?** Email parseforge@protonmail.com with your run ID, your input, and what you expected.

⚠️ **Disclaimer.** This Actor is unofficial and is not affiliated with, endorsed by, or sponsored by United Parcel Service of America, Inc. It collects only publicly available data. You are responsible for using the collected data in compliance with the source's terms of service and applicable data-protection laws, including GDPR, CCPA, and PIPL. Do not use it to collect personal data unlawfully.

# Actor input Schema

## `trackingNumbers` (type: `array`):

List of UPS tracking numbers to look up (e.g. 1Z999AA10123456784). Supports standard 1Z format, Mail Innovations, FGV, and Freight formats.

## `maxItems` (type: `integer`):

How many packages to collect per run.

## `locale` (type: `string`):

Language and country for tracking response (e.g. en_US, fr_FR, de_DE).

## Actor input object example

```json
{
  "trackingNumbers": [
    "1Z999AA10123456784"
  ],
  "maxItems": 10,
  "locale": "en_US"
}
```

# Actor output Schema

## `results` (type: `string`):

Dataset with all scraped items

# 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 '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "trackingNumbers": [
        "1Z999AA10123456784"
    ],
    "maxItems": 10
};

// Run the Actor and wait for it to finish
const run = await client.actor("parseforge/ups-package-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 '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "trackingNumbers": ["1Z999AA10123456784"],
    "maxItems": 10,
}

# Run the Actor and wait for it to finish
run = client.actor("parseforge/ups-package-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 '{
  "trackingNumbers": [
    "1Z999AA10123456784"
  ],
  "maxItems": 10
}' |
apify call parseforge/ups-package-tracking-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,parseforge/ups-package-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 <APIFY_API_TOKEN>` 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/wciwmPaq4aak2csGo/builds/3VOHaYd8IU0BFJP97/openapi.json