Spx Tracking

---

name: spx-tracking license: MIT description: '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.' metadata: {"openclaw":{"requires":{"anyBins":["python3","python"]}}}

---

SPX Express Tracking

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

Invocation

python skills/spx-tracking/scripts/spx_tracking.py  [--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:

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: [] status: | last update: | est. delivery: ~ .

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.