API Carriers for Developers

1. Full List of Carriers

A GET request can retrieve a complete list of all carriers supported by the China Parcels Tracking API.

Example Request

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

Note: Replace {USER_API_SECRET_ACCESS_KEY} with your unique API secret key from your dashboard.

Response Parameters Description

Here’s a detailed explanation of the response parameters:

• error: Error code indicating the result of the request (refer to the error codes list).
• result: An array of objects containing information about the carriers.
  • carrier_id: The unique identifier of the carrier.
  • carrier_name: The name of the carrier (e.g., "China Post", "USPS").
  • carrier_type: The type of carrier (e.g., "post", "courier").
  • carrier_support: Indicates if tracking is supported:
    • 1: Supported.
    • 0: Not supported.
  • carrier_country_code: The country code of the carrier in ISO 3166-1 alpha-2 format (e.g., "cn" for China, "us" for the United States).

Example Response (Partial)

{
  "error": -1,
  "result": [
    {
      "carrier_id": "1",
      "carrier_name": "China Post",
      "carrier_type": "post",
      "carrier_support": "1",
      "carrier_country_code": "cn"
    },
    {
      "carrier_id": "2",
      "carrier_name": "USPS",
      "carrier_type": "post",
      "carrier_support": "1",
      "carrier_country_code": "us"
    },
    {
      "carrier_id": "3",
      "carrier_name": "Canada Post",
      "carrier_type": "post",
      "carrier_support": "1",
      "carrier_country_code": "ca"
    },
    {
      "carrier_id": "4",
      "carrier_name": "Royal Mail",
      "carrier_type": "post",
      "carrier_support": "1",
      "carrier_country_code": "gb"
    }
    ...
  ]
}

Error Codes

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

2. Detailed Information About a Carrier

A GET request can be made to retrieve detailed carrier information using the China Parcels Tracking API.

Example Request

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

Note:

• Replace {USER_API_SECRET_ACCESS_KEY} with your unique API secret key from your dashboard.
• Replace {CARRIER_ID} with the carrier's unique identifier from the above request. 

Response Parameters Description

• error: Error code indicating the result of the request (refer to the error codes list).
• result: An object containing detailed information about the carrier:
  • carrier_id: The unique identifier of the carrier.
  • carrier_name: The name of the carrier (e.g., "USPS").
  • carrier_type: The type of carrier (e.g., "post", "courier").
  • carrier_support: Indicates if tracking is supported:
    • 1: Supported.
    • 0: Not supported.
  • carrier_website: The carrier's official website.
  • carrier_email: The carrier's contact email (if available).
  • carrier_phone: The carrier's contact phone number (if available).
  • carrier_country_code: The country code of the carrier in ISO 3166-1 alpha-2 format.
  • carrier_country_name: The full name of the carrier's country.
  • carrier_icon_background_hex: The carrier's icon's background color (in HEX format).
  • carrier_language_code: The language code used by the carrier in tracking data (e.g., "en" for English).
  • carrier_icon: The URL to the carrier's icon image.
  • carrier_icon_width: The width (in pixels) of the carrier's icon.
  • carrier_icon_height: The height (in pixels) of the carrier's icon.
  • carrier_thumbnail: The URL to the carrier's thumbnail image.
  • carrier_thumbnail_width: The width (in pixels) of the carrier's thumbnail.
  • carrier_thumbnail_height: The height (in pixels) of the carrier's thumbnail.

Example Response

{
  "error": -1,
  "result": {
    "carrier_id": "2",
    "carrier_name": "USPS",
    "carrier_type": "post",
    "carrier_support": "1",
    "carrier_website": "https://www.usps.com",
    "carrier_email": "support@usps.com",
    "carrier_phone": "1-800-222-1811",
    "carrier_country_code": "us",
    "carrier_country_name": "United States of America",
    "carrier_icon_background_hex": "#333366",
    "carrier_language_code": "en",
    "carrier_icon": "https://developers.chinaparcels.com/cdn/images/carriers/icons/0002-usps.png",
    "carrier_icon_width": 256,
    "carrier_icon_height": 256,
    "carrier_thumbnail": "http://developers.chinaparcels.com/cdn/images/carriers/thumbnails/0002-usps.png",
    "carrier_thumbnail_width": 640,
    "carrier_thumbnail_height": 256
  }
}

Error Codes

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