AI助手 NEW 注册
RESTful API

远磐国际 开放API

通过API接口获取港口、机场、船公司、HS编码、邮编等物流数据，轻松集成到您的业务系统

🔐 认证方式

API Key 认证

所有API请求需要在请求头中携带有效的API Key。API Key可在用户中心申请。

1

注册账号

访问 /user-register 注册账号

2

申请API Key

登录用户中心 → 选择套餐 → 申请API Key

3

添加请求头

在请求头中添加 X-API-Key 字段

4

发起请求

调用API接口获取数据

请求头示例 
GET /api/v1/ports HTTP/1.1
Host: ww.yp-sh.cn
X-API-Key: lk_your_api_key_here
📡 数据接口
GET /api/v1/ports 港口数据

获取全球港口列表，支持按关键词搜索、区域筛选和分页查询。

请求参数

参数名 类型 必填 说明
keyword string 否 搜索关键词（港口名称、代码、国家）
region string 否 区域筛选（如：华南、华东、北美）
page int 否 页码，默认1
limit int 否 每页条数，默认20，最大100

响应字段

字段名 类型 说明
id int 港口ID
name_cn string 港口中文名
name_en string 港口英文名
code string 港口代码（如CNGUA）
country string 所属国家
country_en string 国家英文名
country_code string 国家代码（如CN）
region string 所属区域
latitude float 纬度
longitude float 经度

请求示例

cURL 
curl -H "X-API-Key: your_api_key" \
  "https://ww.yp-sh.cn/api/v1/ports?limit=10"

响应示例

JSON Response 
{
  "success": true,
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 100,
    "total_pages": 10
  }
}
GET /api/v1/airports 机场数据

获取全球机场列表，支持按关键词搜索和分页查询。

请求参数

参数名 类型 必填 说明
keyword string 否 搜索关键词（机场名称、IATA代码、ICAO代码）
page int 否 页码，默认1
limit int 否 每页条数，默认20，最大100

响应字段

字段名 类型 说明
id int 机场ID
name_cn string 机场中文名
name_en string 机场英文名
iata_code string IATA代码（如PEK）
icao_code string ICAO代码（如ZBAA）
country string 所属国家
country_en string 国家英文名
country_code string 国家代码
city string 所在城市
city_en string 城市英文名
latitude float 纬度
longitude float 经度

请求示例

cURL 
curl -H "X-API-Key: your_api_key" \
  "https://ww.yp-sh.cn/api/v1/airports?limit=10"

响应示例

JSON Response 
{
  "success": true,
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 100,
    "total_pages": 10
  }
}
GET /api/v1/carriers 船公司数据

获取全球船公司列表，支持按关键词搜索和分页查询。

请求参数

参数名 类型 必填 说明
keyword string 否 搜索关键词（船公司名称、代码）
page int 否 页码，默认1
limit int 否 每页条数，默认20，最大100

响应字段

字段名 类型 说明
id int 船公司ID
name_cn string 船公司中文名
name_en string 船公司英文名
short_name_cn string 中文简称
short_name_en string 英文简称
code string 船公司代码
country string 所属国家
website string 官方网站
description string 公司简介

请求示例

cURL 
curl -H "X-API-Key: your_api_key" \
  "https://ww.yp-sh.cn/api/v1/carriers?limit=10"

响应示例

JSON Response 
{
  "success": true,
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 100,
    "total_pages": 10
  }
}
GET /api/v1/airlines 航空公司数据

获取全球航空公司列表，支持按关键词搜索和分页查询。

请求参数

参数名 类型 必填 说明
keyword string 否 搜索关键词（航空公司名称、IATA代码、ICAO代码）
page int 否 页码，默认1
limit int 否 每页条数，默认20，最大100

响应字段

字段名 类型 说明
id int 航空公司ID
name string 航空公司名称
name_en string 英文名
iata_code string IATA代码（如CA）
icao_code string ICAO代码（如CCA）
callsign string 呼号
country string 所属国家
country_en string 国家英文名
country_code string 国家代码
city string 所在城市
city_en string 城市英文名
website string 官方网站

请求示例

cURL 
curl -H "X-API-Key: your_api_key" \
  "https://ww.yp-sh.cn/api/v1/airlines?limit=10"

响应示例

JSON Response 
{
  "success": true,
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 100,
    "total_pages": 10
  }
}
GET /api/v1/hs-codes HS海关编码数据

获取HS海关编码列表，支持按编码或描述搜索和分页查询。

请求参数

参数名 类型 必填 说明
chapter string 否 章节编码筛选(前2位)
keyword string 否 搜索关键词（HS编码、商品描述）
page int 否 页码，默认1
limit int 否 每页条数，默认20，最大100

响应字段

字段名 类型 说明
id int 编码ID
code string HS编码（如01012100）
description string 商品描述
description_en string 英文描述
chapter string 所属章节
unit string 计量单位
tax_rate float 税率
created_at string 创建时间

请求示例

cURL 
curl -H "X-API-Key: your_api_key" \
  "https://ww.yp-sh.cn/api/v1/hs-codes?limit=10"

响应示例

JSON Response 
{
  "success": true,
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 100,
    "total_pages": 10
  }
}
GET /api/v1/zipcodes 邮编数据

获取全球邮编列表，支持按邮编、城市、州/省搜索和分页查询。

请求参数

参数名 类型 必填 说明
country_code string 否 国家代码筛选
state string 否 州/省筛选
county string 否 县/郡筛选
city string 否 城市筛选
zipcode string 否 邮编精确查询
keyword string 否 关键词搜索
page int 否 页码，默认1
limit int 否 每页条数，默认20，最大100

响应字段

字段名 类型 说明
id int 邮编ID
zipcode string 邮政编码
country_code string 国家代码
country_name string 国家中文名
country_name_en string 国家英文名
state_en string 州/省英文名
county_en string 县/郡英文名
city_en string 城市英文名
latitude float 纬度
longitude float 经度

请求示例

cURL 
curl -H "X-API-Key: your_api_key" \
  "https://ww.yp-sh.cn/api/v1/zipcodes?limit=10"

响应示例

JSON Response 
{
  "success": true,
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 100,
    "total_pages": 10
  }
}
频率限制
频率限制：不同套餐有不同的请求频率限制。免费套餐每小时500次，付费套餐最高可达50000次/小时。

超出限制时将返回 HTTP 429 状态码。响应头中包含以下信息：

Response Headers
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1704067200
❌ 错误码说明
HTTP状态码 错误码 说明
400INVALID_REQUEST请求参数错误
401UNAUTHORIZED缺少或无效的API Key
403IP_NOT_ALLOWEDIP不在白名单内
404NOT_FOUND接口或资源不存在
429RATE_LIMIT_EXCEEDED请求频率超限
500INTERNAL_ERROR服务器内部错误

开始使用 API

注册账号并申请 API Key，即可开始调用

注册账号 申请 API Key API 测试工具

留言咨询

留下您的联系方式，专业顾问将为您提供一对一服务

远磐国际物流 AI助手 在线 · 由 DeepSeek 驱动

您好！我是远磐国际物流 AI助手

可以帮您查港口、船公司、HS编码、货物轨迹等。登录后可查订单、账单、运价。请在下方输入您的问题。