Express Rate Query
Real-time aggregated rates from multiple international courier platforms. Query by country + zip + weight. The system calls all available channels internally and returns a flat, price-ascending result. Covers DHL/UPS/FedEx/TNT/EMS/SF International and more. 3 credits/call.
Endpoint Info
| Endpoint | POST /api/openapi/v1/freight/express/search |
| Credit cost | 3 credits / call |
| Data freshness | Daily |
| Timeout suggestion | Client timeout ≥ 5s |
Request Parameters
| Field | Type | Required | Description | Example |
|---|---|---|---|---|
| destination_country | string | Yes | Destination country, accepts 2-letter ISO code (exact) / Chinese / English (fuzzy)Look up code ↗ | US / United States |
| destination_zip | string | No | Destination zip code (pass as-is for countries with alphanumeric codes; omitting uses nationwide channels, providing it yields more accurate prices) | 90001 |
| destination_city | string | No | Destination city in English (required by some platforms) | Los Angeles |
| weight | number | Yes | Weight in kg (actual weight) | 21.5 |
| length / width / height | number | No | Dimensions in cm (used for volumetric weight calculation) | 40 / 30 / 25 |
| package_type | string | No | Goods type: parcel (default) / document / waterproof bag | Package |
Response Fields
| Field | Type | Description |
|---|---|---|
| resolved.destination_country | object | Echo of the parsed destination country { input, code } |
| list[] | array | Channel list, sorted by price ascending |
| list[].channel_code | string | Channel code (used to reference at order time) |
| list[].channel_name | string | Channel name |
| list[].calc_weight | number | Chargeable weight in kg (max of actual and volumetric) |
| list[].freight | number | Base freight |
| list[].fuel_fee / fuel_rate | number / string | Fuel surcharge amount (already included in price) / percentage string (e.g. "21.50%") |
| list[].surcharge | number | Other surcharges (duties / peak season, etc.) |
| list[].price | number | Total price (freight + fuel_fee + surcharge) |
| list[].currency | string | Currency (default CNY) |
| list[].tt | string | Estimated transit time (e.g. "3-5 business days") |
| list[].remarks | string | Channel remarks (weight/cargo restrictions, peak season, etc.) |
Full curl Example
curl -X POST https://www.5688.cn/api/openapi/v1/freight/express/search \
-H "Content-Type: application/json" \
-H "X-Awice-AppKey: AK_xxxxxxxxxxxxxxxx" \
-H "X-Awice-Timestamp: 1746086400" \
-H "X-Awice-Nonce: a1b2c3d4e5f6a7b8" \
-H "X-Awice-Signature: 7f8e9d6c5b4a..." \
-d '{
"destination_country": "US",
"destination_zip": "90001",
"destination_city": "Los Angeles",
"weight": 21.5,
"length": 40,
"width": 30,
"height": 25,
"package_type": "Package"
}'Successful Response
{
"code": 0,
"msg": "success",
"request_id": "req_xxxxxxxxxxxxxxxx",
"data": {
"resolved": {
"destination_country": { "input": "US", "code": "US" }
},
"list": [
{
"channel_code": "US-DHL-FAST",
"channel_name": "DHL Bulk Express",
"calc_weight": 21.5,
"freight": 681.0,
"fuel_fee": 146.75,
"fuel_rate": "21.50%",
"surcharge": 0,
"price": 827.75,
"currency": "CNY",
"tt": "4-7 business days",
"remarks": "For shipments 21kg+"
},
{
"channel_code": "US-FEDEX-IP",
"channel_name": "FedEx IP Priority",
"calc_weight": 21.5,
"freight": 696.0,
"fuel_fee": 184.5,
"fuel_rate": "26.50%",
"surcharge": 0,
"price": 881.5,
"currency": "CNY",
"tt": "3-5 business days",
"remarks": ""
}
]
},
"credit_used": 3,
"credit_balance": 9493
}Upstream Unavailable Response (no charge)
The system automatically calls all available channels. If all channels time out or error, it returns 5002 and the entire call is not charged. We recommend the client uses exponential backoff and retries 2-3 times.
{
"code": 5002,
"msg": "Upstream channel temporarily unavailable, please retry",
"request_id": "req_xxxxxxxxxxxxxxxx",
"data": {
"resolved": { "destination_country": { "input": "US", "code": "US" } },
"list": []
}
}Notes:
- US zip code must be 5 digits (include leading zeros)
- For FBA freight scenarios, please use the FBA Freight API instead (query by fba_code)
- When dimensions are provided, the system computes volumetric weight automatically; list[].calc_weight reflects the actual chargeable weight
- Internally the system calls multiple channels concurrently. Overall response time is typically 1-3 seconds (we recommend an 8s client timeout).