Real-time Express Tracking check API documentation

中文 | 英文（English）

1.     Real-time Express Tracking Query API

After the user submits the tracking number to the API, it will retrieve the information from the courier company in real-time and return the latest logistics information for this tracking number, including logistics path, status, time, etc.

Note: Please ensure that the frequency of each query for a single tracking number is at least half an hour apart; otherwise, it may result in the tracking number being locked.

1.1     Request URL

https://poll.kuaidi100.com/poll/query.do

1.2     Request Type

post

1.3     Input Parameters

Request Parameters (header)

Request Parameters (body)

1.4     Request Parameters Example  

customer = **********
sign = ******************
param = {
    "com": "yuantong",
    "num": "YT7450353838751",
    "phone": "1011",
    "resultv2": "4",
    "show": "0",
    "order": "desc",
    "lang":"en"
}

1.5     Response F

1.6     Explanation of Waybill Status (state)

Note: To receive advanced logistics status names and values, pass "4" for resultv2.

1.7     Example of Correct Return

JSON Format

{
    "message": "ok",
    "nu": "YT7450353838751",
    "ischeck": "1",
    "com": "yuantong",
    "status": "200",
    "data": [
        {
            "time": "2024-03-09 10:47:53",
            "context": "Your package has been signed for at the Fengchao cabinet in front of Tianjin Tianduan Press Co., Ltd. If you have any questions, please contact the salesperson at 18521184117, the branch phone number is 022-65673899, and the complaint phone number is 022-65673899. Thank you for using YTO Express. Looking forward to serving you again!",
            "ftime": "2024-03-09 10:47:53",
            "areaCode": null,
            "areaName": null,
            "status": "Signed from Locker or Station",
            "location": "天津市,北辰区",
            "areaCenter": null,
            "areaPinYin": null,
            "statusCode": "304"
        },
        {
            "time": "2024-03-09 10:19:51",
            "context": "Your package has arrived at [Fengchao] (Fengchao cabinet at the entrance of Tianjin Tianduan Press Co., Ltd.) on Jinwei Road. Please pick up the package in a timely manner. If you have any questions, please contact the salesperson at 18521184117, the branch phone number is 022-65673899, and the complaint phone number is 022-65673899. Thank you for using YTO Express. Looking forward to serving you again!",
            "ftime": "2024-03-09 10:19:51",
            "areaCode": null,
            "areaName": null,
            "status": "Delivered to Locker or parcel station",
            "location": "天津市,北辰区",
            "areaCenter": null,
            "areaPinYin": null,
            "statusCode": "501"
        },
        {
            "time": "2024-03-09 07:23:55",
            "context": "Li Yanhang (18521184117) from Beichen District, Tianjin is currently delivering the package. Please be patient! If you have any questions, please contact the branch at 022-65673899 or the complaint hotline at 022-65673899. [95161 and 185211 Shanghai numbers are exclusive numbers for YTO agents, please rest assured to answer]",
            "ftime": "2024-03-09 07:23:55",
            "areaCode": "CN120113000000",
            "areaName": "天津,天津,北辰区",
            "status": "Dispatching",
            "location": "天津市,北辰区",
            "areaCenter": "117.139343,39.217817",
            "areaPinYin": "bei chen qu",
            "statusCode": "5"
        },
        {
            "time": "2024-03-09 07:22:05",
            "context": "Your package has arrived at [Department 1, Beichen District, Tianjin]",
            "ftime": "2024-03-09 07:22:05",
            "areaCode": "CN120113000000",
            "areaName": "天津,天津,北辰区",
            "status": "In Transit",
            "location": "天津市,北辰区",
            "areaCenter": "117.139343,39.217817",
            "areaPinYin": "bei chen qu",
            "statusCode": "0"
        },
        {
            "time": "2024-03-08 17:35:48",
            "context": "Your package has left Tianjin Transfer Center and has been sent to Beichen District, Tianjin",
            "ftime": "2024-03-08 17:35:48",
            "areaCode": "CN120113000000",
            "areaName": "天津,天津,北辰区",
            "status": "Trunk Line",
            "location": "天津市,东丽区",
            "areaCenter": "117.139343,39.217817",
            "areaPinYin": "bei chen qu",
            "statusCode": "1002"
        },
        {
            "time": "2024-03-08 17:04:19",
            "context": "Your package has arrived at the Tianjin Transfer Center",
            "ftime": "2024-03-08 17:04:19",
            "areaCode": "CN120000000000",
            "areaName": "天津",
            "status": "Trunk Line",
            "location": "天津市,东丽区",
            "areaCenter": "117.200983,39.084158",
            "areaPinYin": "tian jin",
            "statusCode": "1002"
        },
        {
            "time": "2024-03-08 10:39:53",
            "context": "Your package has left the North China Transfer Center and has been sent to the Tianjin Transfer Center",
            "ftime": "2024-03-08 10:39:53",
            "areaCode": "CN120000000000",
            "areaName": "天津",
            "status": "Trunk Line",
            "location": "北京市,朝阳区",
            "areaCenter": "117.200983,39.084158",
            "areaPinYin": "tian jin",
            "statusCode": "1002"
        },
        {
            "time": "2024-03-08 10:37:01",
            "context": "Your package has arrived at the North China Transfer Center",
            "ftime": "2024-03-08 10:37:01",
            "areaCode": "CN110105000000",
            "areaName": "北京,北京,朝阳区",
            "status": "Trunk Line",
            "location": "北京市,朝阳区",
            "areaCenter": "116.601144,39.948574",
            "areaPinYin": "chao yang qu",
            "statusCode": "1002"
        },
        {
            "time": "2024-03-08 03:50:46",
            "context": "Your package has left the Jinan Transfer Center and has been sent to the North China Transfer Center",
            "ftime": "2024-03-08 03:50:46",
            "areaCode": "CN370112000000",
            "areaName": "山东,济南市,历城区",
            "status": "Trunk Line",
            "location": "济南市,历城区",
            "areaCenter": "117.065237,36.680017",
            "areaPinYin": "li cheng qu",
            "statusCode": "1002"
        },
        {
            "time": "2024-03-08 03:48:09",
            "context": "Your package has arrived at the Jinan Transfer Center",
            "ftime": "2024-03-08 03:48:09",
            "areaCode": "CN370112000000",
            "areaName": "山东,济南市,历城区",
            "status": "Trunk Line",
            "location": "济南市,历城区",
            "areaCenter": "117.065237,36.680017",
            "areaPinYin": "li cheng qu",
            "statusCode": "1002"
        },
        {
            "time": "2024-03-07 22:51:35",
            "context": "Your package has left Jinshui'an, Jinan City, Shandong Province and has been sent to Jinan Transfer Center",
            "ftime": "2024-03-07 22:51:35",
            "areaCode": "CN370105000000",
            "areaName": "山东,济南市,天桥区",
            "status": "Trunk Line",
            "location": "济南市,天桥区",
            "areaCenter": "116.987492,36.678016",
            "areaPinYin": "tian qiao qu",
            "statusCode": "1002"
        },
        {
            "time": "2024-03-07 16:55:46",
            "context": "Your package has been picked up by [Jinshui'an, Jinan City, Shandong Province], recipient: Huo Shengquan (15650027611)",
            "ftime": "2024-03-07 16:55:46",
            "areaCode": "CN370105000000",
            "areaName": "山东,济南市,天桥区",
            "status": "Collected",
            "location": "济南市,天桥区",
            "areaCenter": "116.987492,36.678016",
            "areaPinYin": "tian qiao qu",
            "statusCode": "1"
        }
    ],
    "state": "304",
    "condition": "F00",
    "routeInfo": {
        "from": {
            "number": "CN370105000000",
            "name": "山东,济南市,天桥区"
        },
        "cur": {
            "number": "CN120113000000",
            "name": "天津,天津,北辰区"
        },
        "to": {
            "number": "CN120113000000",
            "name": "天津,天津,北辰区"
        }
    },
    "isLoop": false
}

1.8     Example of Error Return

JSON Format

{
    "result": false,
    "returnCode": "400",
    "message": "找不到对应公司"
}

1.9     Information Code Description

2. Courier Company Codes

Download Table

If the company you need is not on this list, please contact online customer service to add it.

3. Demo Downloads

JAVA Example Code | PHP Example Code | PYTHON Example | PYTHON Example |

Appendix1:

Appendix2: See details:

When querying SF Express logistics information, the error "message": "Courier company parameter error: verification code error" may occur due to the following reasons and suggested handling methods:

1. The Kuaidi100 query interface requires the sender's or recipient's phone number reserved when placing the order with the courier company. For SF Express, this field is mandatory, while for other couriers, it is optional.

2. If the phone number is a landline with an extension, do not include the extension number. If the number is a virtual e-commerce number, include the last four digits after the "-".

3. If the correct phone number is not provided or an incorrect number is submitted, any returned logistics tracking information might be cached data verified by other users. This data is not guaranteed by the query service. The interface requires the phone number to be correctly provided.

4. The correctness of the phone number can be verified through the WeChat Mini Program "SF Express+" on the "Track Express" page.

Example:

- For the number 0755-81234567, any of 075581234567, 81234567, or 4567 can be submitted.

- For the number 13801380000, either 13801380000 or 8000 can be submitted.

- For the number 13801380000-1234, either 13801380001234 or 1234 can be submitted.

SF Express+ Query Example: