# Spx Tracking

> Query SPX Express shipment tracking by tracking number. Call this skill when the user mentions a tracking number matching the SPX format (CNMY..., SPXMY...), or uses Chinese or English trigger phrases in the context of a delivery: "快递" "物流" "到了吗" "到哪了" "派送" "签收" "发货" "tracking" "delivered" "parcel" "package" "delivery" "shipment". Also invoke for CAINIAO / 菜鸟 / 菜鸟集运 tracking numbers — CAINIAO last-mile in Malaysia uses SPX Express, so the same number is queryable via the SPX API. Do NOT use for J&T, Pos Laju, DHL, FedEx, UPS, or any non-SPX courier. The script calls the public SPX API and returns structured JSON, human-readable text, or a one-line summary.

- Skill: `knownasnaffy/spx-tracking` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add knownasnaffy/spx-tracking`
- Raw SKILL.md: https://api.skillmd.com/api/skills/knownasnaffy/spx-tracking/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: MIT
- Author: knownasnaffy (https://skillmd.com/u/knownasnaffy)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/knownasnaffy/spx-tracking

---


# SPX Express Tracking

Query SPX Express (spx.com.my) shipment tracking and return structured results.

## Invocation

```bash
python skills/spx-tracking/scripts/spx_tracking.py <tracking_number> [--format json|text|summary] [--cookie "..."] [--timeout 15]
```

## Arguments

| Argument | Description |
|---|---|
| `tracking_number` | SPX tracking number (format: CNMY..., SPXMY...) |
| `--format` | `json` (default) — structured data; `text` — human-readable; `summary` — one-line status |
| `--cookie` | Browser cookie for authenticated requests (**optional, sensitive** — contains session data, never log or echo to user) |
| `--timeout` | Request timeout in seconds (default: 15) |

## Dependencies

The `run` script auto-creates a venv and installs `requests` on first use. Manual install:
```bash
pip install -r requirements.txt
```

## Output Format Detail

- **`--format json`** (default) — Full JSON. `retcode` is at the top level. Agent checks `retcode == 0` for success; non-zero means API error.
- **`--format text`** — Human-readable sections: status block, timeline, delay analysis, geo route.
- **`--format summary`** — Single-line: `[<tracking_number>] status: <status> | last update: <time> | est. delivery: <min> ~ <max>`.

## Response Schema

| Field | Contents |
|---|---|
| `retcode` | 0 = success; non-zero = API error (check `response.message`) |
| `response` | API-level status message and detail |
| `shipment` | Core info: `tracking_number`, `status`, `receiver_name`, `edd_min`, `edd_max`, `first_event_time`, `last_event_time` |
| `timeline.grouped_events` | Chronological events, deduplicated (use for display) |
| `timeline.raw_events` | All raw events (use for debugging) |
| `geo_route` | Events with GPS: `current_lng`, `current_lat`, `current_full_address` |
| `stay_analysis` | Time between consecutive events (`duration_seconds`) |
| `bottleneck` | The longest stay segment — where the package stalled |

## Intent → Action Mapping

| Observed user intent | Recommended format |
|---|---|
| User provides a SPX tracking number (CNMY..., SPXMY...) | `--format summary` → one-liner reply |
| "快递到哪了" / "where is my package" / "parcel status" | `--format json` → `status` + `last_event_time` + last location |
| "预计什么时候到" / "when will it arrive" / "ETA" | `--format json` → `edd_min` ~ `edd_max` |
| "快递卡住了" / "is it stuck" / "delay" | `--format json` → `bottleneck` section |
| "完整物流" / "full details" / "tracking history" | `--format text` → full human-readable report |

## Usage Constraints

- **SPX Express (spx.com.my) and CAINIAO (菜鸟 / 菜鸟集运)**: This skill covers both SPX Direct and CAINIAO Smart Logistics tracking numbers used in the Malaysia region. CAINIAO's last-mile carrier in Malaysia is SPX Express, so CAINIAO numbers are queryable via this same API.
- **Tracking number format**: SPX numbers start with `CNMY` or `SPXMY`. CAINIAO numbers may have different prefixes but can be searched directly if the user identifies them as CAINIAO/菜鸟/菜鸟集运.
- **Do NOT use for**: J&T, Pos Laju, DHL, FedEx, UPS, Ninja Van, or any other courier.
- **Privacy**: Never output the raw API response body. Only use the structured fields described above.