Docs Menu

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.

POST/api/openapi/v1/schedule/search

1 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#

FieldTypeRequiredDescription
polstringYesOrigin port: standard code, system code, Chinese or English
podstringYesDestination port in the same formats
carrierstringNoCarrier code, name or alias; omit to search supported carriers
pol_country / pod_countrystringNoTwo-letter country codes to disambiguate ports
etd_startstringNoETD start date YYYY-MM-DD; defaults to today
etd_endstringNoInclusive ETD end date YYYY-MM-DD; optional
pageintegerNoPage, default 1, maximum 1000000
limitintegerNoPage 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)#

FieldTypeDescription
resolvedobjectResolved filters; ports include system code and standard locode
total / per_page / current_page / last_pageintegerPagination, ordered by ETD ascending
data[]arraySchedules for the current page; [] if empty
data[].schedule_idstringApp-bound schedule ID; pass it unchanged to details. Do not construct it or use it with another app.
data[].carrierobjectCarrier code, name and name_en
data[].pol / podobjectRoute ports with code, locode, name, name_en and country_code; city queries include related terminals
data[].vessel / voyagestring | nullVessel / voyage
data[].etd / etastring | nullEstimated departure / arrival, YYYY-MM-DD HH:mm:ss
data[].transit_timeinteger | nullTransit days; unknown or zero values return null
data[].is_directboolean | nulltrue: direct; false: transshipment; null: unknown
data[].transshipment_portstring | nullSource transshipment port name or description; null if unavailable
data[].cutoffobjectcy: cargo cut-off; si: SI cut-off; vgm: VGM cut-off; unavailable values are null
data[].servicestring | nullService code when available
data[].updated_atinteger | nullData update time in Unix seconds; data is not guaranteed live
data[].terminalsobjectpol / 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#

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": "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
}
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: 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.

POST/api/openapi/v1/schedule/detail

Current 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#

FieldTypeRequiredDescription
schedule_idstringYesThe schedule ID returned by a search made with the same app
JSON
{
  "schedule_id": "SCH1_FROM_SEARCH"
}

Response Fields (inside data)#

FieldTypeDescription
schedule_id / carrier / pol / pod / vessel / voyage / etd / eta / transit_time / is_direct / transshipment_port / cutoff / service / terminals / updated_atSame as a search recordBasic fields match the selected search record
vessel_infoobjectimo, call_sign, built_year, flag, teu and operator; null when unavailable
legs[]arrayRoute legs from a uniquely matched source plan; [] when unavailable
legs[].seq / vessel / voyage / service / pol / podinteger / string | nullSequence, vessel/voyage, service and source port names; no inferred port codes
legs[].etd / eta / cutoff / availablestring | nullLeg 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_signstring | nullLeg terminals, transport mode, IMO and call sign
port_calls[]arrayPort calls with port, code, eta and etd; [] when unavailable
available / cargo_naturestring | nullAvailability time or source note / cargo nature
extra[]arraykey/value extras: service/haulage notes, CO2, reefer/dangerous cargo cut-offs and source notices; [] if unavailable
JSON
{
  "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.