Shipping Schedule API: Search & Voyage Details
Search sailing schedules by origin, destination, carrier and departure date. Retrieve vessel and voyage, ETD/ETA, transit time, direct or transshipment routing, connections and cut-offs for freight quoting, TMS and shipment planning. Schedules do not guarantee capacity; examples illustrate response structure only.
/api/openapi/v1/schedule/search1 credits per call with results, with up to 50 records per call. Empty results and invalid parameters are free. Each pagination request is a separate call. Existing authentication, plan admission and business-query QPS rules apply.
Request Parameters#
| Field | Type | Required | Description |
|---|---|---|---|
| pol | string | Yes | Origin port: standard code, system code, Chinese or English |
| pod | string | Yes | Destination port in the same formats |
| carrier | string | No | Carrier code, name or alias; omit to search supported carriers |
| pol_country / pod_country | string | No | Two-letter country codes to disambiguate ports |
| etd_start | string | No | ETD start date YYYY-MM-DD; defaults to today |
| etd_end | string | No | Inclusive ETD end date YYYY-MM-DD; optional |
| page | integer | No | Page, default 1, maximum 1000000 |
| limit | integer | No | Page size, default 20, capped at 50 |
Reuses freight port matching and city/terminal expansion. Ambiguity returns 1002 with candidates; specify a code or country. code is the system code; locode is the maintained standard UN/LOCODE, or null.
Date bounds include the start and end days. Rows without ETD do not match. ETD, ETA and cut-offs preserve their date/time precision without an inferred time zone or UTC marker and are estimates. See updated_at for the data update time.
Response Fields (inside data)#
| Field | Type | Description |
|---|---|---|
| resolved | object | Resolved filters; ports include system code and standard locode |
| total / per_page / current_page / last_page | integer | Pagination, ordered by ETD ascending |
| data[] | array | Schedules for the current page; [] if empty |
| data[].schedule_id | string | App-bound schedule ID; pass it unchanged to details. Do not construct it or use it with another app. |
| data[].carrier | object | Carrier code, name and name_en |
| data[].pol / pod | object | Route ports with code, locode, name, name_en and country_code; city queries include related terminals |
| data[].vessel / voyage | string | null | Vessel / voyage |
| data[].etd / eta | string | null | Estimated departure / arrival, YYYY-MM-DD HH:mm:ss |
| data[].transit_time | integer | null | Transit days; unknown or zero values return null |
| data[].is_direct | boolean | null | true: direct; false: transshipment; null: unknown |
| data[].transshipment_port | string | null | Source transshipment port name or description; null if unavailable |
| data[].cutoff | object | cy: cargo cut-off; si: SI cut-off; vgm: VGM cut-off; unavailable values are null |
| data[].service | string | null | Service code when available |
| data[].updated_at | integer | null | Data update time in Unix seconds; data is not guaranteed live |
| data[].terminals | object | pol / pod origin and destination terminals; null if unavailable |
Empty Results#
No matches return HTTP 200, code=0 and data.data=[] with no credit charge. Recognized carriers without available schedules also return an empty list. Adjust the search criteria or try again later. Pages beyond the last page also return an empty list at no charge.
Supported carriers: COSCO, MSC, ONE, HPL, YML, MSK, HMM, EMC, CMA, KMTC, ZIM, OOCL and TSLINE. Coverage, field availability and update times may vary by carrier and route. Schedules do not guarantee capacity or bookability.
Request and Response Examples#
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": "COSCO",
"name_en": "COSCO"
},
"pol": {
"code": "CNSZN",
"locode": "CNSZX",
"name": "Shenzhen",
"name_en": "shenzhen",
"country_code": "CN"
},
"pod": {
"code": "USLSA",
"locode": "USLAX",
"name": "Los Angeles",
"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: missing/invalid parameters, unknown ports or carriers. 1002: ambiguous candidates. Invalid parameters consume no credits. See authentication documentation for signing.
Schedule Details#
Search first, then pass schedule_id unchanged. IDs are bound to the app that obtained them. Ports or a carrier alone cannot request details. IDs below illustrate the schema; replace them with a real search result.
/api/openapi/v1/schedule/detailCurrent price: 0 credits per non-empty detail (default 0, with no additional search charge). Configurable in the dashboard. Empty results and invalid IDs are free. Sign requests with the same app; business API QPS limits apply.
Request Parameters#
| Field | Type | Required | Description |
|---|---|---|---|
| schedule_id | string | Yes | The schedule ID returned by a search made with the same app |
{
"schedule_id": "SCH1_FROM_SEARCH"
}Response Fields (inside data)#
| Field | Type | Description |
|---|---|---|
| schedule_id / carrier / pol / pod / vessel / voyage / etd / eta / transit_time / is_direct / transshipment_port / cutoff / service / terminals / updated_at | Same as a search record | Basic fields match the selected search record |
| vessel_info | object | imo, call_sign, built_year, flag, teu and operator; null when unavailable |
| legs[] | array | Route legs from a uniquely matched source plan; [] when unavailable |
| legs[].seq / vessel / voyage / service / pol / pod | integer / string | null | Sequence, vessel/voyage, service and source port names; no inferred port codes |
| legs[].etd / eta / cutoff / available | string | null | Leg departure, arrival, cut-off and availability, preserving source precision (date or minutes may be supplied) |
| legs[].terminal_from / terminal_to / transport_mode / vessel_imo / vessel_call_sign | string | null | Leg terminals, transport mode, IMO and call sign |
| port_calls[] | array | Port calls with port, code, eta and etd; [] when unavailable |
| available / cargo_nature | string | null | Availability time or source note / cargo nature |
| extra[] | array | key/value extras: service/haulage notes, CO2, reefer/dangerous cargo cut-offs and source notices; [] if unavailable |
{
"code": 0,
"msg": "success",
"request_id": "req_example",
"data": {
"carrier": {
"code": "COSCO",
"name": "COSCO",
"name_en": "COSCO"
},
"pol": {
"code": "CNSZN",
"locode": "CNSZX",
"name": "Shenzhen",
"name_en": "shenzhen",
"country_code": "CN"
},
"pod": {
"code": "USLSA",
"locode": "USLAX",
"name": "Los Angeles",
"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
}If sailing information is unavailable, the response is HTTP 200, code=0 and data=[]; search again. When extended details are unavailable, existing basic fields are returned, missing values are null, and legs/port_calls/extra are []. Field availability may vary by carrier and route.
1001: missing, modified or malformed ID, or an ID belonging to another app. Use the sailing ID returned by the same app's schedule search. Data may change; rely on the current search result.