Home Open Platform DocsReference Data

Reference Data

Resolve anything your users type — "Ningbo", "宁波" or "CNNGB" — into the standard codes the rate APIs expect. Covers 4,300+ sea ports, 9,500+ airports, 130 carriers, 340+ airlines and 250+ countries.

Billing & daily free quota

The search endpoints are for filling gaps — verifying a port code, debugging, or the occasional name that is not in the common sets. The free quota is a **total for the whole subscription period** (not per day); beyond it, calls are billed in credits.

Account status	Free quota (total)	Daily cap	Notes
No active plan	Not available	—	Claim the trial pack or buy a plan first
Trial pack	200 calls	100/day	Total for the whole period — not per day
Paid plan	500 calls	200/day	Total for the whole period — not per day

Beyond the free quota

The API keeps serving data, billed at 1 credit(s) per call — spending the same credits you use for rate queries. Returns 3001 once you run out.

Need port data in bulk? Not with the search endpoints

To build a port/airport picker, or to load port codes into your own system, use the Common Reference Sets below — every priced port and airport in one call, **free, unlimited, and it consumes no quota at all**. The search quota is not meant for bulk retrieval.

Five search endpoints

All five work identically: pass a keyword, get back up to 5 candidates ranked by popularity.

Dataset	Endpoint	Records
Sea ports	GET /api/openapi/v1/dict/port	4,300+
Airports	GET /api/openapi/v1/dict/airport	9,500+
Ocean carriers	GET /api/openapi/v1/dict/carrier	130
Airlines	GET /api/openapi/v1/dict/airline	340+
Countries / regions	GET /api/openapi/v1/dict/country	250+

Request parameters

Field	Type	Required	Description	Example
keyword	string	Yes	Search term. Accepts Chinese, English or a standard code; minimum 2 characters. Standard codes (5-char port, 3-char airport) are matched exactly	宁波 / Ningbo / CNNGB

For the country endpoint, keyword is optional — leave it empty to get the popular countries.

Response fields

Field	Type	Description
data[].code	string	Standard code — pass it straight into pol / pod on the rate APIs
data[].name	string	Chinese name
data[].name_en	string	English name
data[].country_code	string	2-letter ISO country code (returned for ports and airports; empty for carriers and airlines)

Request example

# keyword accepts Chinese, English or a standard code
curl -G https://www.5688.cn/api/openapi/v1/dict/port \
  --data-urlencode "keyword=宁波" \
  -H "X-Awice-AppKey: AK_xxxxxxxxxxxxxxxx" \
  -H "X-Awice-Timestamp: 1746086400" \
  -H "X-Awice-Nonce: a1b2c3d4e5f6a7b8" \
  -H "X-Awice-Signature: 7f8e9d6c5b4a3f2e1d0c9b8a7e6d5c4b3a2f1e0d9c8b7a6e5d4c3b2a1f0e9d8c"

Response example

{
  "code": 0,
  "msg": "success",
  "request_id": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "data": [
    {
      "code": "CNNBO",
      "name": "宁波",
      "name_en": "Ningbo",
      "country_code": "CN"
    }
  ],
  "quota": { "cost": 0, "remain": 1500 },
  "credit_used": 0,
  "credit_balance": 1500
}

Same-name ports return multiple candidates

"San Antonio" exists in Chile, the US and Argentina, so the API returns all of them and you can let the user pick. Or skip the picking entirely — hand the keyword straight to a rate API and it will query every matching port and merge the results.

{
  "code": 0,
  "msg": "success",
  "request_id": "b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7",
  "data": [
    { "code": "CLSAN", "name": "圣安东尼奥", "name_en": "San Antonio", "country_code": "CL" },
    { "code": "USSAT", "name": "圣安东尼奥", "name_en": "San Antonio", "country_code": "US" },
    { "code": "ARSAE", "name": "圣安东尼奥东", "name_en": "San Antonio Este", "country_code": "AR" }
  ],
  "quota": { "cost": 0, "remain": 1499 },
  "credit_used": 0,
  "credit_balance": 1499
}

Common Reference Sets

Fetch the commonly-used ports, airports, carriers, airlines and countries in one call and cache them in your own system for pickers and autocomplete. Far faster than hitting the search API on every keystroke — and it doesn't consume your daily quota.

Free, unlimited calls, available as soon as you register.

Endpoint

Path	GET /api/openapi/v1/dict/popular
Credit cost	Free (0 credits)
Rate limit	Unlimited
Plan required	None — available on any account

Request parameters

Field	Type	Required	Description	Example
type	string	No	Dataset to fetch; omit it to get all five at once	port / airport / carrier / airline / country

How many records per dataset

Dataset	Records	Notes
Sea ports	~1,500	Only ports we actually have rates for — a port with no rates would be useless to you anyway
Airports	~550	Only airports we actually have rates for
Ocean carriers	All 130	Carrier codes are public industry information — nothing held back
Airlines	All 340+	Same
Countries / regions	All 250+	Same

"Common" means **the ports and airports we actually have rates for** — not "top ranked". It covers every major hub (Shanghai, Ningbo, Shenzhen, Los Angeles, Hamburg; PVG, PEK, CAN, LAX, NRT...). Long-tail entries with no rates are not included — look those up by name with the search endpoints above when you need them.

Request example

curl -G https://www.5688.cn/api/openapi/v1/dict/popular \
  -H "X-Awice-AppKey: AK_xxxxxxxxxxxxxxxx" \
  -H "X-Awice-Timestamp: 1746086400" \
  -H "X-Awice-Nonce: a1b2c3d4e5f6a7b8" \
  -H "X-Awice-Signature: 7f8e9d6c5b4a3f2e1d0c9b8a7e6d5c4b3a2f1e0d9c8b7a6e5d4c3b2a1f0e9d8c"

Response example

{
  "code": 0,
  "msg": "success",
  "request_id": "d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9",
  "data": {
    "total": 1733,
    "limits": { "port": 500, "airport": 500, "carrier": 0, "airline": 0, "country": 0 },
    "data": {
      "port": [
        { "code": "CNSZN", "locode": "CNSZX", "name": "深圳", "name_en": "shenzhen", "country_code": "CN" },
        { "code": "CNSHA", "locode": "CNSHA", "name": "上海", "name_en": "shanghai", "country_code": "CN" }
      ],
      "carrier": [
        { "code": "MSK", "name": "马士基", "name_en": "MAERSK-SEALAND" }
      ],
      "country": [
        { "code": "DE", "name": "德国", "name_en": "Germany" }
      ]
    }
  },
  "quota": { "cost": 0, "remain": 1500 },
  "credit_used": 0,
  "credit_balance": 1500
}

Ports also return locode (the international standard code). Your own port records most likely use standard codes — use it to line them up with our code values.

Next: SDK Downloads