船期查询与航次详情 API
按起运港、目的港、船公司和开船日期查询船期,返回船名航次、ETD/ETA、航程、直达或中转、中转港及截止时间。适用于货代询价、TMS 和运输计划;船期不代表可订舱位,示例仅演示响应结构。
/api/openapi/v1/schedule/search有结果每次 1 积分,单次最多返回 50 条。空结果及参数错误不扣费,翻页按新的调用计费。鉴权、套餐准入及 QPS 规则沿用业务查询接口。
请求参数#
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| pol | string | 是 | 起运港,标准码、系统码、中文、英文均可 |
| pod | string | 是 | 目的港,支持同上 |
| carrier | string | 否 | 船公司代码、名称或别名;不填查已接入船司 |
| pol_country / pod_country | string | 否 | 两位国家代码,用于港口消歧 |
| etd_start | string | 否 | 开船起始日期 YYYY-MM-DD,默认今天 |
| etd_end | string | 否 | 开船结束日期 YYYY-MM-DD,包含当天;不填不设结束日 |
| page | integer | 否 | 页码,默认 1,最大 1000000 |
| limit | integer | 否 | 每页条数,默认 20,最大 50 |
复用运价港口匹配及城市/子港扩展。存在歧义返回 1002 和候选,请指定代码或国家。code 是系统码,locode 是已维护的标准 UN/LOCODE,缺失时为 null。
日期范围包含起止当天,没有 ETD 的航次不参与匹配。ETD、ETA 和截止时间保留原有日期精度,不补造时区或 UTC 标记,均为预计时间;数据更新时间见 updated_at。
返回字段(业务 data 内)#
| 字段 | 类型 | 说明 |
|---|---|---|
| resolved | object | 解析后的查询条件;港口同时回显内部 code 和标准 locode |
| total / per_page / current_page / last_page | integer | 分页信息,按 ETD 升序 |
| data[] | array | 当前页船期;查无为 [] |
| data[].schedule_id | string | 当前应用绑定的航次标识;原样传给详情接口,不能跨应用使用或自行拼接 |
| data[].carrier | object | 船公司 code、name、name_en |
| data[].pol / pod | object | 查询航线起运/目的港 code、locode、name、name_en、country_code;城市港会扩展子港 |
| data[].vessel / voyage | string | null | 船名 / 航次 |
| data[].etd / eta | string | null | 预计开船 / 到港时间,YYYY-MM-DD HH:mm:ss |
| data[].transit_time | integer | null | 航程天数;未知或 0 返回 null |
| data[].is_direct | boolean | null | true 直达,false 中转,null 未知 |
| data[].transshipment_port | string | null | 来源记录的中转港名称或描述;无则 null,不补造港口码 |
| data[].cutoff | object | cy 截关 / si 截 SI / vgm 截 VGM;每项缺失返回 null |
| data[].service | string | null | 航线代码(如有) |
| data[].updated_at | integer | null | 数据更新时间,Unix 秒;不保证实时 |
| data[].terminals | object | pol / pod 起运、目的码头,缺失为 null |
查无处理#
查无正常返回 HTTP 200、code=0、data.data=[],当次不扣积分。船公司能匹配但暂无可用船期时同样返回空列表。可调整查询条件或稍后再查询。超出总页数时同样返回空列表且不扣积分。
当前支持 COSCO、MSC、ONE、HPL、YML、MSK、HMM、EMC、CMA、KMTC、ZIM、OOCL、TSLINE。数据覆盖、字段完整性和更新时间可能因船公司及航线而异;船期不代表舱位或可订舱承诺。
请求与响应示例#
curl -X POST https://www.5688.cn/api/openapi/v1/schedule/search \
-H "Content-Type: application/json" \
-H "X-Awice-AppKey: AK_xxxxxxxxxxxxxxxx" \
-H "X-Awice-Timestamp: [timestamp]" \
-H "X-Awice-Nonce: [nonce]" \
-H "X-Awice-Signature: [signature]" \
-d '{
"pol": "CNSZX",
"pod": "USLAX",
"carrier": "COSCO",
"page": 1,
"limit": 20
}'{
"code": 0,
"msg": "success",
"request_id": "req_example",
"data": {
"resolved": {
"pol": {
"input": "CNSZX",
"code": "CNSZN",
"locode": "CNSZX"
},
"pod": {
"input": "USLAX",
"code": "USLSA",
"locode": "USLAX"
},
"carrier": {
"code": "COSCO"
},
"etd_start": "2026-10-07",
"etd_end": null
},
"total": 1,
"per_page": 20,
"current_page": 1,
"last_page": 1,
"data": [
{
"carrier": {
"code": "COSCO",
"name": "中远海运",
"name_en": "COSCO"
},
"pol": {
"code": "CNSZN",
"locode": "CNSZX",
"name": "深圳",
"name_en": "shenzhen",
"country_code": "CN"
},
"pod": {
"code": "USLSA",
"locode": "USLAX",
"name": "洛杉矶",
"name_en": "los angeles,ca",
"country_code": "US"
},
"vessel": "EXAMPLE VESSEL",
"voyage": "001E",
"etd": "2026-11-01 12:00:00",
"eta": "2026-11-20 08:00:00",
"transit_time": 19,
"is_direct": true,
"transshipment_port": null,
"cutoff": {
"cy": "2026-10-30 12:00:00",
"si": null,
"vgm": null
},
"service": null,
"updated_at": 1791331200,
"schedule_id": "SCH1_FROM_SEARCH",
"terminals": {
"pol": null,
"pod": null
}
}
]
},
"credit_used": 1
}{
"code": 0,
"msg": "success",
"request_id": "req_example",
"data": {
"resolved": {
"pol": {
"code": "CNSZN",
"locode": "CNSZX"
},
"pod": {
"code": "USLSA",
"locode": "USLAX"
},
"carrier": {
"code": "COSCO"
}
},
"total": 0,
"per_page": 20,
"current_page": 1,
"last_page": 1,
"data": []
},
"credit_used": 0
}1001:缺参、日期无效、无匹配港口或船公司;1002:候选歧义。参数错误不扣积分。标准签名详见鉴权文档。
船期详情#
先调用船期查询,再将返回的 schedule_id 原样传入。标识绑定创建它的应用;不能只传港口或船公司直接查详情。以下标识仅为结构演示,请替换为真实查询结果。
/api/openapi/v1/schedule/detail当前非空详情每次 0 积分(默认 0,不重复收取查询费用),后台可调整;空结果、无效标识不扣费。仍需同一应用签名鉴权,并沿用业务接口 QPS 限制。
请求参数#
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| schedule_id | string | 是 | 当前应用船期查询结果中的航次标识 |
{
"schedule_id": "SCH1_FROM_SEARCH"
}返回字段(业务 data 内)#
| 字段 | 类型 | 说明 |
|---|---|---|
| schedule_id / carrier / pol / pod / vessel / voyage / etd / eta / transit_time / is_direct / transshipment_port / cutoff / service / terminals / updated_at | 同查询单条记录 | 基础字段与对应查询记录一致 |
| vessel_info | object | imo、call_sign、built_year、flag、teu、operator;缺失为 null |
| legs[] | array | 完整航程分段;只有源数据明确提供且精确匹配时返回,缺失为 [] |
| legs[].seq / vessel / voyage / service / pol / pod | integer / string | null | 序号、各段船名航次、航线、起终港名称(来源文本,不推造标准码) |
| legs[].etd / eta / cutoff / available | string | null | 各段开船、到港、截止与可提柜时间,保留来源精度,可能只有日期或分钟 |
| legs[].terminal_from / terminal_to / transport_mode / vessel_imo / vessel_call_sign | string | null | 各段码头、运输方式、IMO 与呼号 |
| port_calls[] | array | 挂靠港 port / code / eta / etd;缺失为 [] |
| available / cargo_nature | string | null | 可提柜时间或来源说明 / 货物性质 |
| extra[] | array | key/value 额外信息:航线说明、拖运方式、碳排放、冷藏/危险品截止等;缺失为 [] |
{
"code": 0,
"msg": "success",
"request_id": "req_example",
"data": {
"carrier": {
"code": "COSCO",
"name": "中远海运",
"name_en": "COSCO"
},
"pol": {
"code": "CNSZN",
"locode": "CNSZX",
"name": "深圳",
"name_en": "shenzhen",
"country_code": "CN"
},
"pod": {
"code": "USLSA",
"locode": "USLAX",
"name": "洛杉矶",
"name_en": "los angeles,ca",
"country_code": "US"
},
"vessel": "EXAMPLE VESSEL",
"voyage": "001E",
"etd": "2026-11-01 12:00:00",
"eta": "2026-11-20 08:00:00",
"transit_time": 19,
"is_direct": true,
"transshipment_port": null,
"cutoff": {
"cy": "2026-10-30 12:00:00",
"si": null,
"vgm": null
},
"service": null,
"updated_at": 1791331200,
"schedule_id": "SCH1_FROM_SEARCH",
"terminals": {
"pol": null,
"pod": null
},
"vessel_info": {
"imo": null,
"call_sign": null,
"built_year": null,
"flag": null,
"teu": null,
"operator": null
},
"available": null,
"cargo_nature": null,
"extra": [],
"port_calls": [],
"legs": []
},
"credit_used": 0
}航次信息暂不可用时返回 HTTP 200、code=0、data=[],请重新查询。扩展详情未提供时仍返回已有基础信息,缺失标量为 null,legs/port_calls/extra 为 []。字段完整性可能因船公司及航线而异。
1001:标识缺失、被修改、格式不正确或属于其他应用。请使用同一应用船期查询返回的航次标识;数据可能更新,以当前查询结果为准。