# 17TRACK Package Tracking Scraper (`muhammadafzal/17track-package-tracking-scraper`) Actor

Track packages across 17TRACK carriers and export normalized status, routes, delivery estimates, carrier handoffs, and checkpoint history.

- **URL**: https://apify.com/muhammadafzal/17track-package-tracking-scraper.md
- **Developed by:** [Muhammad Afzal](https://apify.com/muhammadafzal) (community)
- **Categories:** E-commerce, Automation, Other
- **Stats:** 3 total users, 2 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.00 / 1,000 tracked packages

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?

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

## 17TRACK Package Tracking Scraper

Track public package numbers across 17TRACK-supported carriers and export a consistent dataset containing the current shipment status, carrier handoffs, route, delivery estimate, latest checkpoint, and event history.

### What this Actor extracts

| Field | Meaning |
|---|---|
| `trackingNumber` | Identifier supplied in the Actor input |
| `displayTrackingNumber` | Identifier shown by 17TRACK |
| `carriers` / `carrierIds` | Detected carriers and 17TRACK carrier IDs |
| `status` / `statusCategory` | Source status plus a stable lifecycle category |
| `statusDescription` | Latest public tracking update |
| `originCountry` / `destinationCountry` | Public route countries when available |
| `estimatedDelivery` / `daysInTransit` | Delivery window and elapsed transit time |
| `latestEvent` / `events` | Latest checkpoint and full carrier event history |
| `sourceUrl` / `retrievedAt` | Provenance and retrieval timestamp |

Use it for order-support workflows, shipment monitoring, logistics analysis, marketplace operations, and carrier-handoff reconciliation. It is not an official 17TRACK API client, does not log into private accounts, and does not bypass CAPTCHA or access controls.

### Input

```json
{
  "trackingNumbers": ["7777777770"],
  "language": "en",
  "includeRaw": false,
  "requestTimeoutSecs": 45,
  "proxyConfiguration": { "useApifyProxy": true }
}
```

`trackingNumbers` accepts 1–10 values. The default `7777777770` invokes 17TRACK's public demonstration result and is marked `isDemoData: true`; replace it with real package IDs for production use. Duplicate numbers are removed. Invalid IDs are reported in `OUTPUT` and never billed as results.

`language` localizes page text. `includeRaw` keeps the page-owned structured shipment object when available. `requestTimeoutSecs` is a per-package bound. Apify Proxy is enabled by default; select a residential group only if the standard cloud route is challenged.

### Output example

```json
{
  "trackingNumber": "7777777770",
  "displayTrackingNumber": "TestNumber00017",
  "carrierIds": [],
  "carriers": ["USPS(International Parcels)", "China Post"],
  "status": "In transit",
  "subStatus": null,
  "statusDescription": "CHINA,WUHAN, Processed Through Facility",
  "statusCategory": "in_transit",
  "daysInTransit": 5,
  "originCountry": "China",
  "destinationCountry": "United States",
  "estimatedDelivery": "2022-04-05 - 2022-04-06",
  "latestEvent": {
    "timestamp": "2022-03-25 19:57",
    "description": "CHINA,WUHAN, Processed Through Facility",
    "location": "CHINA",
    "carrier": null
  },
  "events": [],
  "sourceUrl": "https://t.17track.net/en#nums=7777777770",
  "retrievedAt": "2026-09-09T00:00:00.000Z",
  "isDemoData": true,
  "raw": null
}
```

The default dataset stays homogeneous: only validated package records are written. `OUTPUT` in the default key-value store contains `DATA`, `EMPTY`, `BLOCKED`, `REJECTED`, or `FAILED`, plus attempted/delivered counts and warnings.

### Pricing

This Actor uses pay per event.

| Event | Price |
|---|---:|
| Actor start | $0.00005 |
| One tracked package record | $0.03 |

One delivered package therefore costs about `$0.03005`; five delivered records cost about `$0.15005`. Empty, blocked, invalid, and failed lookups do not create dataset-item charges. Apify enforces the run charge cap before additional lookups begin.

### Reliability and limits

The Actor opens the public 17TRACK result page in a consistent Chrome session and captures the structured page-owned tracking response. If that structure is unavailable, it falls back to the rendered tracking view. A blocked lookup is retried once with a fresh browser/proxy session. HTTP 403/429, verification pages, upstream failure, no-match results, and timeouts remain distinct diagnostics.

Results depend on what 17TRACK and the underlying carriers expose publicly. Newly created labels may take 24–48 hours to appear. Some carriers limit request volume or destination detail, and 17TRACK may require verification during high-risk traffic. The Actor will not solve CAPTCHAs or fabricate missing shipments.

### API example

```bash
curl -X POST "https://api.apify.com/v2/acts/YOUR_ACTOR_ID/runs?token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"trackingNumbers":["YOUR_TRACKING_NUMBER"],"language":"en","includeRaw":false,"requestTimeoutSecs":45}'
```

Avoid placing real tracking numbers in public logs or shared Task presets. Tracking history can reveal approximate locations and shipping relationships; retain and share output only for legitimate package-support and logistics purposes. Use of this Actor must comply with 17TRACK's terms, carrier terms, privacy law, and applicable platform rules. 17TRACK and carrier names are used descriptively; this Actor is not affiliated with or endorsed by them.

# Actor input Schema

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

Use this to track 1–10 package IDs across supported carriers. Enter one ID per row, for example 7777777770 (17TRACK's public test lookup). Values must contain 4–80 letters, numbers, or hyphens.

## `language` (type: `string`):

Use this to choose the 17TRACK result-page language. Supported presets are English, German, Spanish, French, Italian, Dutch, Polish, Portuguese, and Turkish; default is en.

## `includeRaw` (type: `boolean`):

Use this for debugging fields not yet normalized. It includes the page-owned 17TRACK shipment object when available and can make records much larger; default is false.

## `requestTimeoutSecs` (type: `integer`):

Use this to control how long each package may wait for 17TRACK to finish. Choose 20–90 seconds; default 45. This is not the whole Actor run timeout.

## `proxyConfiguration` (type: `object`):

Use this when 17TRACK challenges cloud traffic or needs a matching geography. Apify Proxy is enabled by default; select residential only when the normal route is blocked.

## Actor input object example

```json
{
  "trackingNumbers": [
    "7777777770"
  ],
  "language": "en",
  "includeRaw": false,
  "requestTimeoutSecs": 45,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

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

Schema-validated package tracking records in the default dataset.

## `summary` (type: `string`):

Outcome classification, counts, warnings, and billing parity fields.

# 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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("muhammadafzal/17track-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 = {}

# Run the Actor and wait for it to finish
run = client.actor("muhammadafzal/17track-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 '{}' |
apify call muhammadafzal/17track-package-tracking-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,muhammadafzal/17track-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/52FRSBoluZqUV6y0Q/builds/00oQgq9U9gMFtF5bK/openapi.json