文档目录

船期查询与航次详情 API

按起运港、目的港、船公司和开船日期查询船期,返回船名航次、ETD/ETA、航程、直达或中转、中转港及截止时间。适用于货代询价、TMS 和运输计划;船期不代表可订舱位,示例仅演示响应结构。

POST/api/openapi/v1/schedule/search

有结果每次 1 积分,单次最多返回 50 条。空结果及参数错误不扣费,翻页按新的调用计费。鉴权、套餐准入及 QPS 规则沿用业务查询接口。

请求参数#

字段类型必填说明
polstring是起运港,标准码、系统码、中文、英文均可
podstring是目的港,支持同上
carrierstring否船公司代码、名称或别名;不填查已接入船司
pol_country / pod_countrystring否两位国家代码,用于港口消歧
etd_startstring否开船起始日期 YYYY-MM-DD,默认今天
etd_endstring否开船结束日期 YYYY-MM-DD,包含当天;不填不设结束日
pageinteger否页码,默认 1,最大 1000000
limitinteger否每页条数,默认 20,最大 50

复用运价港口匹配及城市/子港扩展。存在歧义返回 1002 和候选,请指定代码或国家。code 是系统码,locode 是已维护的标准 UN/LOCODE,缺失时为 null。

日期范围包含起止当天,没有 ETD 的航次不参与匹配。ETD、ETA 和截止时间保留原有日期精度,不补造时区或 UTC 标记,均为预计时间;数据更新时间见 updated_at。

返回字段(业务 data 内)#

字段类型说明
resolvedobject解析后的查询条件;港口同时回显内部 code 和标准 locode
total / per_page / current_page / last_pageinteger分页信息,按 ETD 升序
data[]array当前页船期;查无为 []
data[].schedule_idstring当前应用绑定的航次标识;原样传给详情接口,不能跨应用使用或自行拼接
data[].carrierobject船公司 code、name、name_en
data[].pol / podobject查询航线起运/目的港 code、locode、name、name_en、country_code;城市港会扩展子港
data[].vessel / voyagestring | null船名 / 航次
data[].etd / etastring | null预计开船 / 到港时间,YYYY-MM-DD HH:mm:ss
data[].transit_timeinteger | null航程天数;未知或 0 返回 null
data[].is_directboolean | nulltrue 直达,false 中转,null 未知
data[].transshipment_portstring | null来源记录的中转港名称或描述;无则 null,不补造港口码
data[].cutoffobjectcy 截关 / si 截 SI / vgm 截 VGM;每项缺失返回 null
data[].servicestring | null航线代码(如有)
data[].updated_atinteger | null数据更新时间,Unix 秒;不保证实时
data[].terminalsobjectpol / pod 起运、目的码头,缺失为 null

查无处理#

查无正常返回 HTTP 200、code=0、data.data=[],当次不扣积分。船公司能匹配但暂无可用船期时同样返回空列表。可调整查询条件或稍后再查询。超出总页数时同样返回空列表且不扣积分。

当前支持 COSCO、MSC、ONE、HPL、YML、MSK、HMM、EMC、CMA、KMTC、ZIM、OOCL、TSLINE。数据覆盖、字段完整性和更新时间可能因船公司及航线而异;船期不代表舱位或可订舱承诺。

请求与响应示例#

BASH
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
}'
JSON
{
  "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
}
JSON
{
  "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 原样传入。标识绑定创建它的应用;不能只传港口或船公司直接查详情。以下标识仅为结构演示,请替换为真实查询结果。

POST/api/openapi/v1/schedule/detail

当前非空详情每次 0 积分(默认 0,不重复收取查询费用),后台可调整;空结果、无效标识不扣费。仍需同一应用签名鉴权,并沿用业务接口 QPS 限制。

请求参数#

字段类型必填说明
schedule_idstring是当前应用船期查询结果中的航次标识
JSON
{
  "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_infoobjectimo、call_sign、built_year、flag、teu、operator;缺失为 null
legs[]array完整航程分段;只有源数据明确提供且精确匹配时返回,缺失为 []
legs[].seq / vessel / voyage / service / pol / podinteger / string | null序号、各段船名航次、航线、起终港名称(来源文本,不推造标准码)
legs[].etd / eta / cutoff / availablestring | null各段开船、到港、截止与可提柜时间,保留来源精度,可能只有日期或分钟
legs[].terminal_from / terminal_to / transport_mode / vessel_imo / vessel_call_signstring | null各段码头、运输方式、IMO 与呼号
port_calls[]array挂靠港 port / code / eta / etd;缺失为 []
available / cargo_naturestring | null可提柜时间或来源说明 / 货物性质
extra[]arraykey/value 额外信息:航线说明、拖运方式、碳排放、冷藏/危险品截止等;缺失为 []
JSON
{
  "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:标识缺失、被修改、格式不正确或属于其他应用。请使用同一应用船期查询返回的航次标识;数据可能更新,以当前查询结果为准。