Zhiyong Parcel Tracking

Use when a user asks to track a parcel, package, shipment, order delivery, or waybill. Required: one tracking_number (5–64 letters, digits, or hyphens). Optional: carrier (defaults to UniUni; UniUni is the only supported carrier today) and language (defaults to English); additional carriers are planned for future support. A named unsupported carrier returns outcome=unsupported_carrier without querying UniUni. Returns structured found, outcome, carrier, supported_carriers, delivery status, estimated delivery, carrier-local scan events, and approximate city/region. Street addresses, coordinates, staff, internal IDs, and raw carrier data are excluded. Inputs and filtered results are logged with source IP and client context for up to 30 days or 1,000 requests.

{
  "type": "object",
  "properties": {
    "tracking_number": {
      "type": "string",
      "minLength": 5,
      "maxLength": 64,
      "pattern": "^[A-Za-z0-9-]+$",
      "description": "Parcel tracking or waybill number. Current carrier coverage is UniUni."
    },
    "carrier": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "description": "Optional carrier name; defaults to UniUni when omitted. UniUni is currently the only supported carrier; another named carrier is rejected without a lookup."
    },
    "language": {
      "type": "string",
      "enum": [
        "zh",
        "en"
      ],
      "default": "en",
      "description": "Language for event titles, details and locations. Defaults to English."
    }
  },
  "required": [
    "tracking_number"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "tracking_number": {
      "type": "string",
      "description": "The requested parcel tracking or waybill number."
    },
    "found": {
      "type": "boolean",
      "description": "Whether the carrier found a matching parcel."
    },
    "outcome": {
      "type": "string",
      "enum": [
        "delivered",
        "in_transit",
        "not_found",
        "invalid",
        "unsupported_carrier",
        "configuration_error",
        "carrier_error",
        "rate_limited"
      ],
      "description": "Normalized lookup outcome, including validation and temporary service errors."
    },
    "carrier": {
      "type": "string",
      "description": "Carrier requested by the caller, or UniUni when omitted. Only UniUni is currently supported."
    },
    "supported_carriers": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Carriers currently available through this service."
    },
    "status": {
      "type": "string",
      "description": "Localized, normalized latest delivery status when a parcel is found."
    },
    "status_code": {
      "type": "string",
      "description": "Carrier status code, when available."
    },
    "status_kind": {
      "type": "string",
      "enum": [
        "delivered",
        "in_transit",
        "exception"
      ],
      "description": "Normalized delivery state."
    },
    "estimated_delivery": {
      "type": "string",
      "description": "Carrier-provided estimated delivery date, when available."
    },
    "events": {
      "type": "array",
      "description": "Privacy-filtered scan history in carrier-local display time; street addresses and internal fields are excluded.",
      "items": {
        "type": "object",
        "properties": {
          "time": {
            "type": "string",
            "description": "Event time as displayed by the carrier, without UTC conversion."
          },
          "time_basis": {
            "type": "string",
            "enum": [
              "carrier_local"
            ]
          },
          "status": {
            "type": "string",
            "description": "Localized, normalized event title."
          },
          "location": {
            "type": "string",
            "description": "Approximate city or region, when available."
          },
          "detail": {
            "type": "string",
            "description": "Safe, normalized event explanation, when available."
          }
        },
        "required": [
          "time",
          "time_basis",
          "status"
        ],
        "additionalProperties": false
      }
    },
    "detail": {
      "type": "string",
      "description": "Actionable explanation for validation, carrier, configuration, or rate-limit errors."
    }
  },
  "required": [
    "found",
    "outcome",
    "carrier",
    "supported_carriers"
  ],
  "additionalProperties": false
}