API Parcels for Developers

1. Identify Carriers by Tracking Number (Lookup)

A GET request can retrieve a complete list of all supported carriers by the China Parcels Tracking API. This endpoint is helpful when determining which carriers are associated with a given tracking number before initiating a tracking request.

Example Request

curl -X GET "https://developers.chinaparcels.com/api/v1/user/{USER_API_SECRET_ACCESS_KEY}/parcels/{TRACKING_NUMBER}/lookup"

Note:

  • Replace {USER_API_SECRET_ACCESS_KEY} with your unique API secret key from your dashboard.
  • Replace {TRACKING_NUMBER} to your parcel tracking number.

Response Parameters Description

  • error: Error code indicating the result of the request (see error codes below).
  • result: An array of carrier IDs that match the tracking number.

Example Response

{ "error": -1, "result": ["2", "4"] }

In this response:

  • 2 (USPS) and 4 (Royal Mail) are the carrier IDs that match the tracking number. You can list all carrier IDs in the Carrier API section. 

Error Codes

  • -1 - Request successful;
  • 0 - User not found;
  • 1 - Out of balance;

2. Track the Parcel by Tracking Number

To track your parcel, we offer two methods: first, we automatically determine the carrier using our algorithm. Alternatively, you can specify the carrier to track the parcel.

2.1 Example Request With Auto-detect Carrier

curl -X GET "https://developers.chinaparcels.com/api/v1/user/{USER_API_SECRET_ACCESS_KEY}/parcels/{TRACKING_NUMBER}/track"

Note:

  • Replace {USER_API_SECRET_ACCESS_KEY} with your unique API secret key from your dashboard.
  • Replace {TRACKING_NUMBER} to your parcel tracking number.

2.2 Example Request for Current Carrier ID

curl -X GET "https://developers.chinaparcels.com/api/v1/user/{USER_API_SECRET_ACCESS_KEY}/parcels/{TRACKING_NUMBER}/track/{CARRIER_ID}"

Note:

  • Replace {USER_API_SECRET_ACCESS_KEY} with your unique API secret key from your dashboard.
  • Replace {TRACKING_NUMBER} to your parcel tracking number.
  • Replace {CARRIER_ID} to carrier ID from the Carrier API section or Lookup (above).

Response Parameters Description

Main Response Object

  • error: Error code indicating the result of the request (see error codes below).
  • result: Object containing parcel tracking and carrier data.

Tracking Data (carrier_tracking_data)

An array of tracking events:

  • time: Timestamp of the event (Unix format).
  • info: Description of the event.
  • location: Location where the event occurred.
  • date: Event date and time in YYYY-MM-DD HH:mm:ss format.

Parcel Data (parcel_other_data)

Details about the parcel:

  • postal_product: The postal product or service used (e.g., "Priority Mail Express International").
  • reference_tracking_numbers: Additional reference tracking numbers array, if available.
  • description: A description of the parcel was provided by the carrier.
  • recipient: Recipient information, if available.
  • sender: Sender information, if available.
  • scheduled_delivery: Estimated delivery information from the carrier.
  • weight: Weight of the parcel.
  • dimensions: Dimensions of the parcel.

Parcel Origin and Destination

  • parcel_origin_country_code: ISO 3166-1 alpha-2 country code of the origin.
  • parcel_destination_country_code: ISO 3166-1 alpha-2 country code of the destination.

Carrier Data (carrier)

Information about the carrier:

  • carrier_website: Official website of the carrier.
  • carrier_email: Contact email of the carrier.
  • carrier_phone: Contact the carrier's phone number.
  • carrier_type: Type of the carrier (e.g., "post", "carrier").
  • carrier_support: Indicates if the carrier is supported (1: Yes, 0: No).
  • carrier_country_name: Country where the carrier is based.
  • carrier_icon: URL to the carrier's icon image.
  • carrier_icon_width: Width of the carrier icon (in pixels).
  • carrier_icon_height: Height of the carrier icon (in pixels).
  • carrier_thumbnail: URL to the carrier's thumbnail image.
  • carrier_thumbnail_width: Width of the carrier thumbnail (in pixels).
  • carrier_thumbnail_height: Height of the carrier thumbnail (in pixels).
  • carrier_name: Name of the carrier.
  • carrier_country_code: ISO 3166-1 alpha-2 country code of the carrier.
  • carrier_language_code: Language code the carrier uses for tracking data (e.g., "en").

Delivery Estimates

  • estimate_delivery_days: Estimated number of days until delivery.
  • estimate_delivery_date: Estimated delivery date (YYYY-MM-DD) from the first tracking date.

Parcel Status

  • status: Current status of parcel:
    • 1 - Not Found;
    • 2 - In Transit;
    • 3 - Pick Up; 
    • 4 - Delivered;
    • 5 - Alert;
    • 6 - Undelivered;
    • 7 - Expired.

Example Response

{
  "error": -1,
  "result": {
    "carrier_tracking_data": [
      {
        "time": 1733313180,
        "info": "Customs Clearance.",
        "location": "TURKIYE",
        "date": "2024-12-04 11:53:00"
      },
      {
        "time": 1733313000,
        "info": "Processed Through Facility.",
        "location": "TURKIYE",
        "date": "2024-12-04 11:50:00"
      }
    ],
    "parcel_other_data": {
      "postal_product": "Priority Mail Express International",
      "reference_tracking_numbers": [
        "REF_NUMBER_01",
        "REF_NUMBER_02"
      ],
      "description": "parcel description from carrier",
      "recipient": "recipient info",
      "sender": "sender info",
      "scheduled_delivery": "scheduled delivery info from carrier",
      "weight": "parcel weight",
      "dimensions": "parcel dimensions"
    },
    "parcel_origin_country_code": "us",
    "parcel_destination_country_code": "tr",
    "status": 2,
    "carrier": {
      "carrier_website": "https://www.usps.com",
      "carrier_email": "support@usps.com",
      "carrier_phone": "1-800-222-1811",
      "carrier_type": "post",
      "carrier_icon_background_hex": "#333366",
      "carrier_support": "1",
      "carrier_country_name": "United States of America",
      "carrier_icon": "http://developers.chinapost-track.com.local/cdn/images/carriers/icons/0002-usps.png",
      "carrier_icon_width": 256,
      "carrier_icon_height": 256,
      "carrier_thumbnail": "http://developers.chinapost-track.com.local/cdn/images/carriers/thumbnails/0002-usps.png",
      "carrier_thumbnail_width": 640,
      "carrier_thumbnail_height": 256,
      "carrier_name": "USPS",
      "carrier_country_code": "us",
      "carrier_id": "2",
      "carrier_language_code": "en"
    },
    "estimate_delivery_days": 16,
    "estimate_delivery_date": "2024-12-13"
  }
}

Error Codes

  • -1 - Request successful;
  • 0 - User not found;
  • 1 - Out of balance;
  • 3 - Carrier is not found by this number (Auto-detect Carrier);