基础数据字典

把「宁波」「Ningbo」「CNNGB」这类任意写法，解析成运价接口认识的标准代码。收录 4300+ 海运港口、9500+ 国际机场、130 家船公司、340+ 航空公司、250+ 国家地区。

计费与每日免费额度

字典搜索是「查漏补缺」用的——验证某个港口码、调试、偶尔碰到常用集之外的名字。免费额度是**整个有效期的总量**（不是每天），用完后按积分计费。

账号状态	免费额度（总量）	每日上限	说明
未订阅任何套餐	不可用	—	需先领取体验包或购买套餐
体验包	200 次	100 次/天	整个有效期的总量，不是每天
付费套餐	500 次	200 次/天	整个有效期的总量，不是每天

超出免费额度之后

接口继续正常返回数据，按 1 积分 / 次计费——花的是你查运价的积分。账户没有可用积分时返回 3001。

要批量拿港口数据？别用搜索接口

做港口 / 机场下拉框，或者需要把港口代码存进自己的系统——请用下面的「常用字典集」，一次拿走全部有运价的港口和机场，**免费、不限次数、不消耗任何额度**。搜索接口的额度不是为批量获取准备的。

五个搜索接口

五个接口用法完全一致：传 keyword，返回最多 5 条候选，按热门度排序。

字典	接口路径	收录量
海运港口	GET /api/openapi/v1/dict/port	4300+
国际机场	GET /api/openapi/v1/dict/airport	9500+
船公司	GET /api/openapi/v1/dict/carrier	130
航空公司	GET /api/openapi/v1/dict/airline	340+
国家 / 地区	GET /api/openapi/v1/dict/country	250+

请求参数

字段名	类型	必填	说明	示例
keyword	string	是	搜索词，支持中文 / 英文 / 标准代码三种写法，最少 2 个字符。传标准代码时（港口 5 位、机场 3 位）走精确匹配	宁波 / Ningbo / CNNGB

国家接口的 keyword 可以留空 —— 留空时返回热门国家列表。

响应字段

字段名	类型	说明
data[].code	string	标准代码，直接拿去填运价接口的 pol / pod
data[].name	string	中文名
data[].name_en	string	英文名
data[].country_code	string	2 位 ISO 国家代码（港口 / 机场返回；船公司 / 航空公司为空）

请求示例

# keyword 支持中文 / 英文 / 标准代码三种写法
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"

响应示例

{
  "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
}

同名港口会返回多条候选

「圣安东尼奥」这类同名港口分布在智利、美国、阿根廷，接口会把候选都返回，你可以让用户从中挑一个。也可以干脆不挑 —— 直接把关键词交给运价接口，它会自动查询所有同名港口并合并结果。

{
  "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
}

常用字典集

一次拿到常用的港口、机场、船公司、航司和国家，缓存进你自己的系统做下拉框 / 输入联想。比用户每敲一个字母就打一次搜索接口快得多，也不消耗你的每日字典额度。

免费，不限调用次数，注册即可使用。

接口信息

接口路径	GET /api/openapi/v1/dict/popular
积分消耗	免费（0 积分）
调用限制	不限次数
套餐要求	无，注册即可用

请求参数

字段名	类型	必填	说明	示例
type	string	否	字典类型；不传则一次返回全部 5 类	port / airport / carrier / airline / country

每类返回多少条

字典	条数	说明
海运港口	约 1500	只含我们有运价数据的港口 —— 没有运价的港口给了你也查不到东西
国际机场	约 550	只含我们有运价数据的机场
船公司	全部 130	船公司代码是行业公开信息，不做保留
航空公司	全部 340+	同上
国家 / 地区	全部 250+	同上

「常用」的定义是**我们有运价数据的**，不是「排名靠前的」——覆盖了上海、宁波、深圳、洛杉矶、汉堡以及 PVG / PEK / CAN / LAX / NRT 等全部主力港口和机场。没有运价的冷门港口不在这里；真需要时用上面的搜索接口按名称查即可。

请求示例

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"

响应示例

{
  "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
}

港口会额外返回 locode（国际标准代码）。你手上的港口数据用的多半是标准码，靠它就能跟我们的 code 对齐。

下一步：SDK 下载