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#

ArgumentDescriptiontracking_numberSPX tracking number (format: CNMY..., SPXMY...)--format``json (default) — structured data; text — human-readable; summary — one-line status--cookieBrowser cookie for authenticated requests ( optional, sensitive — contains session data, never log or echo to user)--timeoutRequest 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#

FieldContentsretcode0 = success; non-zero = API error (check response.message)responseAPI-level status message and detailshipmentCore info: tracking_number, status, receiver_name, edd_min, edd_max, first_event_time, last_event_time``timeline.grouped_eventsChronological events, deduplicated (use for display)timeline.raw_eventsAll raw events (use for debugging)geo_routeEvents with GPS: current_lng, current_lat, current_full_address``stay_analysisTime between consecutive events ( duration_seconds)bottleneckThe longest stay segment — where the package stalled

Intent → Action Mapping#

Observed user intentRecommended formatUser 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.