1. 文档附录
Shipxy
  • 船讯网API服务概述
  • 文档目录
  • 注册与创建应用
  • 多语言SDK引入
  • 标准API服务
    • 1 船舶查询
      • 1.1 船舶位置查询
        • 1.1.1 单船位置查询
        • 1.1.2 多船位置查询
        • 1.1.3 船队位置查询
      • 1.2 船舶模糊查询
      • 1.3 周边船舶查询
      • 1.4 区域船舶查询
      • 1.5 船舶船籍查询
      • 1.6 船舶档案查询
      • 1.7 档案服务扩展
    • 2 港口查询
      • 2.1 港口信息查询
      • 2.2 港口当前靠泊船查询
      • 2.3 港口当前到锚船查询
      • 2.4 港口预抵船舶查询
    • 3 历史行为
      • 3.1 船舶历史轨迹查询
      • 3.2 船舶互相搭靠记录查询
    • 4 挂靠记录
      • 4.1 船舶历史挂靠记录
      • 4.2 船舶挂靠指定港口记录
      • 4.3 船舶当前挂靠信息
      • 4.4 港口挂靠历史船舶
    • 5 航线规划
      • 5.1 点到点航线规划
      • 5.2 港到港航线规划
      • 5.3 预计到达时间(ETA)查询
    • 6 天气气象
      • 6.1 新全球气象
        • 6.1.1 实时气象数据
        • 6.1.2 未来气象预报
      • 6.2 全球台风
        • 6.2.1 获取全球台风列表
        • 6.2.2 获取单个台风信息
      • 6.3 国内港口潮汐
        • 6.3.1 查询国内潮汐观测站列表
        • 6.3.2 查询单个观测站潮汐详情
      • 6.4 全球港口潮汐
        • 6.4.1 查询全球潮汐观测站列表
        • 6.4.2 查询单个观测站潮汐详情
      • 6.5 海区气象
      • 6.6 单点海洋气象
      • 6.7 历史气象记录
    • 7 海图GIS平台开发
      • 7.1 快速入门：从注册到接入
      • 7.2 地图引擎基础：地图控制与业务绘制
      • 7.3 船位展示服务
      • 7.4 历史轨迹服务
      • 7.5 图层与气象服务
      • 7.6 航线绘制与区域回放服务
      • 7.7 Vue项目接入指南
      • 7.8 API Key后端代理接入
      • 7.9 坐标系转换指南
      • 7.10 私有化部署开发指南
        • 01 私有化地图加载绘制
        • 02 船舶与轨迹绘制实践
        • 03 气象图层效果绘制
    • 8 海事数据
      • 8.1 航行警告查询
    • 9 监控推送
      • 9.1 监控船队管理
        • 9.1.1 创建船队
        • 9.1.2 更新船队信息
        • 9.1.3 查询船队
        • 9.1.4 删除船队
        • 9.1.5 船队船舶增加
        • 9.1.6 船队船舶批量更新
        • 9.1.7 船队船舶删除
      • 9.2 区域监控推送
        • 9.2.1 区域创建
        • 9.2.2 区域更新
        • 9.2.3 区域查询
        • 9.2.4 区域删除
        • 9.2.5 区域监控推送内容
      • 9.3 船舶航速提醒推送
        • 9.3.1 新增船舶订阅
        • 9.3.2 删除订阅船舶信息
        • 9.3.3 查询订阅船舶列表
        • 9.3.4 船舶航速异常推送
      • 9.4 实时船位推送
      • 9.5 船舶到离港事件推送
      • 9.6 船舶动态ETA推送
      • 9.7 船舶AIS信号消失事件推送
      • 9.8 船舶搭靠事件推送
    • 文档附录
      • 船舶类型对照表
      • 服务码返回说明
      • 海区对照表
      • 航行状态对照表
      • 绕航节点清单
      • 航标类型对照表
      • 区域船二进制解析说明
      • 常见问题
  • AI智能体应用
    • AI大模型接入MCP服务
    • 智能体场景应用
      • 运力资源智能体
      • 船舶风控智能体
      • 运输规划智能体
      • 航次时效预测智能体
      • 船舶安全监控智能体
      • 多式联运协同智能体
      • 大宗贸易态势分析智能体
  • 视频监控AI识别预警服务
    • 视频监控服务接入指南
    • 视频监控API服务说明
    • 视频监控场景应用指南
    • 视频监控服务FAQ与最佳实践
  • 场景化开发示例
    • 大宗物流运输智能决策平台
      • 1、港口运力监控与找船
      • 2、船队货运跟踪与 ETA
      • 3、货运异常预警中心
      • 4、大宗航运态势分析与经营决策大屏
      • 5、航次时效预测与滞期费测算
      • 6、航次能效与碳强度管理
    • 海上设施安全监管与决策平台
      • 1、监管区域与事件推送（总览大屏）
      • 2、设施周边安全监控
      • 3、偏航识别与轨迹回放
      • 4、气象海况与航行警告
      • 5、海上安全态势监管大屏与执法效能分析
      • 6、水域通航密度与碰撞风险预测
      • 7、设施运维作业窗口智能排程与船舶调度
  1. 文档附录

常见问题

第一部分 新手入门：零基础快速理解#

1. 什么是 API？船讯网 API 能帮我做什么？#

Q1：API 到底是什么？#

API（Application Programming Interface，应用程序编程接口）可以理解为一个"数据窗口"：你的程序按照约定好的格式发一个请求过去，船讯网的服务器就把数据返回给你。不需要安装任何软件，只要能发 HTTP 请求（浏览器、命令行、任何编程语言都可以），就能拿到数据。

Q2：船讯网 API 能拿到什么数据？#

船讯网 API 是一套基于 HTTP 请求的船舶数据服务，覆盖九大场景：船舶查询（船在哪、是什么船）、港口查询（港口里有哪些船）、历史行为（船过去走过哪）、挂靠记录（船什么时候到过哪个港）、航线规划（两港之间多远、怎么走）、气象天气（海上风浪、台风、潮汐）、海事数据（航行警告）、海图应用（电子海图与地图瓦片）、监控推送（船进出区域自动通知你）。当前版本 V3.0。全部服务能力总览见官方开发文档首页：船讯网 API 服务概述。

Q3：我没有开发团队，只是想先看看数据长什么样，可以吗？#

可以。官方开发文档的每个接口页面都提供在线调试功能：不需要写任何代码，在网页上填好参数点一下，就能看到真实返回的数据样例（如单船位置查询的在线调试）。前提是你已经在控制台创建了自己的 API Key（见 Q5）。

2. 什么是 API Key？怎么申请？#

Q4：API Key 是什么？#

API Key（授权码）是一串字符，相当于你的"账号密码+通行证"，每次请求都要带上它，服务器据此识别你是谁、有没有权限、还剩多少调用额度。创建应用与获取 Key 的完整流程见官方文档注册与创建应用。

Q5：怎么注册和拿到 Key？#

1.
打开船讯网首页，点右上角头像注册（填写手机号和公司信息即可；个人开发者做技术调研时公司信息可填"无"），或直接在 API 控制台注册
2.
登录 API 控制台，进入「应用管理」模块，点击「创建应用」，生成应用 Key
3.
选择创建试用 Key 即可获得初始测试权限，做功能性测试；正式商用需创建正式 Key 并联系商务开通权限
规则：一个账户最多注册 5 个 Key；第一个 Key 自带初始测试权限；一个账户最多 1 个试用 Key。详见注册与创建应用。

Q6：Key 怎么保管？#

Key 不要写死在对外公开的代码或前端页面里，避免泄露被盗用
可在控制台给 Key 设置 IP 白名单（【访问限制】），只允许指定服务器调用
怀疑泄露时：锁定 IP、换 Key

Q7：以前开通过旧版 API 的 Key，现在怎么办？#

旧 Key 关联新控制台：官网暂无自助绑定入口，联系商务协助关联
旧版控制台入口：API 官网控制台的子菜单【旧版控制台】
迁移到新版本：官网列出的均为新版服务，需对照开发文档调整请求 URL 和参数名（标准 API 服务说明）

Q8：直接复制官方文档示例里的 Key 请求数据，为什么返回 status 14？#

官方文档所有示例中的演示 Key（1F6D701272402D1E7D8D316CCE519123）已绑定示例域名，任何人都无权使用，直接复制请求会返回 status 14（来源域错误）。这是新手最常踩的坑。解决办法：在控制台创建自己的 Key 再调用。各状态码含义见官方服务码返回说明。

3. 第一次调用 API 需要几步？#

Q9：完整的调用流程是什么？#

四步走：
1.
注册登录控制台，创建应用 Key（注册与创建应用）
2.
看文档：在 apidocs.shipxy.com 找到要用的接口，记下请求地址和参数
3.
拼请求：把 Key 和参数拼进 URL 发出去，例如查询 MMSI 为 413961925 的船：
https://api.shipxy.com/apicall/v3/GetSingleShip?key=你的Key&mmsi=413961925（单船位置查询文档）
4.
解析返回：服务器返回 JSON 格式数据，按字段取出使用

Q10：HTTP GET 和 POST 是什么？查询参数怎么拼？#

GET：把参数直接写在 URL 里，? 后面跟 参数名=值，多个参数用 & 连接。船讯网绝大多数查询接口都是 GET
POST：参数放在请求体里传输，适合参数较长的情况。例如电子围栏创建时点位超过 100 个就必须用 POST（区域创建）
浏览器地址栏直接粘贴 GET 请求 URL 就能测试，是最简单的调试方式

4. 返回的数据长什么样？怎么看懂？#

Q11：JSON 是什么格式？#

JSON 是一种通用的数据文本格式，用花括号 {} 包对象、方括号 [] 包列表，每个字段是 "字段名": 值。所有主流编程语言都能一行代码解析。

Q12：船讯网返回的结构怎么解读？#

所有接口统一返回三层结构：status（状态码，0 表示成功）、msg（状态信息，成功时为空，失败时是错误说明）、data（真正的数据）。以单船位置查询为例（官方文档真实示例）：
{
    "status": 0,
    "msg": "",
    "data": {
        "mmsi": 413961925,
        "ship_name": "WANHONGYUAN369",
        "ship_cnname": "皖鸿远369",
        "data_source": 0,
        "ship_type": 70,
        "length": 68,
        "width": 13,
        "draught": 4.8,
        "dest": "TAIZHOU,CN",
        "destcode": "CNTZO",
        "navistat": 0,
        "lat": 32.192517,
        "lng": 119.628093,
        "sog": 6.2,
        "cog": 80.8,
        "last_time": "2025-04-28 16:05:48"
    }
}
读法：这艘 MMSI 为 413961925 的船叫"皖鸿远369"，正在（navistat=0 航行中）北纬 32.19°、东经 119.63° 以 6.2 节的速度航行，目的地是泰州港，最后一次上报位置是 2025-04-28 16:05:48。

Q13：status 不是 0 怎么办？#

先看 msg 的错误说明。常见情况：key 无效或无权限、调用次数超限、参数格式错误、来源域错误（status 14）。完整状态码与含义见官方服务码返回说明。排查顺序见附录 D"通用排查思路"。

Q14：常见的 status 错误码有哪些？#

状态码含义常见处理
0成功-
14来源域错误不要用文档演示 Key，换成自己创建的 Key
21无权限 / key 无效控制台核对权限，联系商务开通
29 / 429请求频率超限降低调用频率，3 分钟后自动解除
100参数错误对照接口文档核对参数名与格式
400敏感船（Sensitive）见 Q34，提供证据联系船讯网核实
完整清单以官方服务码返回说明为准。

5. 不会写代码怎么办？支持哪些语言？#

Q15：支持哪些开发语言？#

官方提供多语言 SDK，直接可用：Java、JavaScript、Python、C#。SDK 封装了底层逻辑，调用更简洁，引入方式见官方文档多语言 SDK 引入。

Q16：完全不懂编程能用吗？#

可以先用文档页的在线调试直接看数据；要做成系统（监控大屏、物流跟踪页面等）则需要开发能力，或者联系商务沟通定制化服务。

6. 什么是 AIS？数据从哪来？#

Q17：AIS 是什么？#

AIS（Automatic Identification System，船舶自动识别系统）是船舶通过 VHF 频段自动广播自身信息的系统。船上设备每隔几秒到几分钟自动播报一次：我是谁（MMSI、船名）、我在哪（经纬度）、我往哪开（航向航速）、我去哪里（目的港）等。国际公约要求一定吨位以上的商船强制安装。

Q18：船讯网的 AIS 数据从哪来？#

两个通道：
岸基 AIS：陆地上的接收基站，覆盖沿海约 30-50 海里范围。船讯网的基站只接收 AIS 播报并回传服务器，不能发信号
卫星 AIS：通过低轨卫星接收 AIS 信号，覆盖全球远洋海域
返回字段 data_source：0 = 岸基或船基基站，1 = 卫星基站。底层实际接入来源更丰富（自有基站、合作基站、卫星数据等），每条数据内部可精确追溯来源。服务总览见船讯网 API 服务概述。

Q19：数据更新频率如何？#

平均更新频率：岸基平均小于 1.1 分钟，卫星平均小于 12 分钟。每天有动态更新的船舶（独立 MMSI）超过 48 万艘，动态报文（去重）每天超过 7 亿条，全球 AIS 数据包每月约 1TB（未压缩）。历史轨迹最早可查到 2012 年（船舶历史轨迹查询）。

7. MMSI、IMO、呼号、船名有什么区别？#

Q20：这几个船舶标识分别是什么？#

标识说明特点
MMSI海上移动业务识别码，9 位数字船讯网以它作为船舶唯一标识；船舶买卖、换国籍时可能变更
IMO国际海事组织编号，7 位数字终身不变；仅远洋商船具备，有 IMO 才有劳氏档案
呼号无线电通信呼号字母+数字，各国海事机构核发；部分小船没有
船名中文/英文名称可能重名、更名、简写，不能作为唯一匹配依据
使用建议：唯一性优先级 IMO > MMSI > 船名/呼号；动态数据与静态数据通过 MMSI 关联，禁止用船名模糊匹配做数据关联。MMSI 变更时，用船名（未变更前提下）通过船舶模糊查询 SearchShip 找到新 MMSI——用 IMO 查询时，该接口会返回该 IMO 下曾经使用过的所有 MMSI 记录。

8. AIS 数据分哪几类？字段怎么看？#

Q21：一次船位查询返回的三类数据？#

1.
静态数据：船舶固有属性，长期不变——船名、呼号、IMO、MMSI、船长、船宽、船舶类型
2.
动态数据：实时航行状态，秒/分钟级更新——经度、纬度、船速（sog）、航迹向（cog）、航首向（hdg）、航行状态（navistat）
3.
航程数据：随航次变化——吃水（draught）、目的港（dest/destcode）、预计到达时间（eta）

Q22：常见字段的单位？#

经纬度：度，WGS84 坐标系
sog 船速：节（1 节 = 1 海里/小时 ≈ 1.852 公里/小时）
cog/hdg：度，正北为 0°，顺时针
length/width/draught：米
时间字段：北京时间字符串 + Unix 时间戳（秒）成对返回

Q23：哪些值代表"无效数据"？#

navistat = -1、sog = -1、cog = -1 表示无效；hdg = 511 或超过 360 均为无效（AIS 设备会随机上报异常值，小部分未剔除）。解析时要做过滤。航行状态编码遵循国际 AIS 标准，完整对照见官方航行状态对照表：0=航行中、1=锚泊、2=失控、3=搁浅、4=受限通航、5=靠泊停泊、6=作业中等。

Q24：目的港、ETA 这些字段可以直接信吗？#

目的港（dest）、预计到达时间（eta）、吃水均为船员手动填报，存在滞后更新、随意填报、简写错填等问题，仅作辅助参考：ETA 可能是上一航次旧值且系统不做修正；目的港经标准化匹配（如"LYG"→"LIANYUNGANG,CN"），实在无法识别时返回空值。内河小船、渔船的 IMO/ETA/目的港为空属正常现象。要更准的 ETA，用"精确 ETA 查询"服务（系统按剩余里程÷平均航速计算，见预计到达时间 ETA 查询）。

Q25：ship_type 船型代码去哪查？#

AIS 船型字段是数字代码（如 70=杂货船）。官方提供完整船舶类型对照表，做船型筛选（如港口预抵船舶查询的 ship_type 参数）或数据解读时对照使用。

9. 常用单位与概念扫盲#

Q26：海里、节是什么？#

1 海里 = 1852 米 ≈ 1.852 公里；1 节 = 1 海里/小时。普通货船航速约 10-15 节。

Q27：什么是挂靠、搭靠、航次、电子围栏？#

挂靠（Port Call）：船舶到达港口并在泊位或锚地停靠的行为记录。系统按地理围栏判定：船驶入港口围栏、减速至近乎停留并持续足够时间（约 10 分钟）即生成一条挂靠记录
搭靠（Docking）：两条船贴近停靠或并排行驶超过 5 分钟（典型如海上加油），判定口径见船舶互相搭靠记录查询
航次：船讯网体系采用最简化的"两港航次"定义，一个多港班轮航次会被拆成多个两港航段
电子围栏：在海图上画一个多边形区域，船舶进出时自动触发推送提醒（区域监控推送）
锚地：港口外供船舶等待靠泊的水域；预抵：预计将要到达某港的船舶

Q28：什么是 WGS84 坐标系？GCJ-02 纠偏是什么？#

WGS84 是 GPS/北斗使用的国际通用坐标标准，船讯网 API 全部坐标都是 WGS84。国内地图厂商（高德、百度）使用加密后的 GCJ-02 坐标，把 WGS84 的船位直接叠加到这些地图上会有偏移，需要做"纠偏"（WGS84→GCJ-02）转换。船讯网海图 GIS 平台示例已内置纠偏方法，专门指南见坐标系转换指南。

10. 查询（拉）和推送（推）两种模式怎么选？#

Q29：查询类 API 和推送服务有什么区别？#

查询（拉模式）：你的程序主动发请求要数据。适合按需查询、历史数据分析、偶发使用
推送（推模式）：你提供一个回调地址（URL），船讯网主动把数据 POST 到你的服务器。分固定周期推送（实时船位、动态 ETA，各 10 分钟一次）和事件触发推送（到离港、区域围栏、信号消失、搭靠、航速异常）
选型建议：需要持续监控一批船（如自有船队实时位置）→ 推送，避免高频轮询消耗额度且实时性好；需要查历史、做报表分析 → 查询。两者常配合使用。

第二部分 场景选型指南：我要做 XX，该用哪些服务？#

每个场景给出：适用对象、详细场景描述、推荐接口组合（附开发文档链接）。官方还提供了成体系的场景化开发示例，含 API 能力全景表与通用技术约束（UTC 时间戳、调用频率建议、降级策略），建议选型时一并阅读。

场景一：货物物流跟踪（货主/货代/物流企业）#

适用对象：货主、贸易商、货代、航运物流企业。
场景描述：货交给船公司之后，货主最关心三件事——船现在开到哪了、还有几天到卸货港、有没有异常。实现方式是以船名/MMSI 锁定船舶，持续获取实时位置与系统计算的 ETA，叠加航线规划做偏航预警，配合到离港事件推送自动确认"装货完成/抵港/离港"，形成从发货到收货的全链路时效跟踪。官方完整示例见大宗物流运输与船队货运跟踪与 ETA。
推荐接口组合：
单船位置查询 GetSingleShip / 多船位置查询 GetManyShip / 船队位置查询 GetFleetShip——按监控规模选择
船舶模糊查询 SearchShip——用船名/IMO 锁定目标船
预计到达时间 ETA 查询 GetSingleETAPrecise——系统计算的精确 ETA
港到港航线规划 PlanRouteByPort / 点到点航线规划 PlanRouteByPoint——基准航线与里程
船舶到离港事件推送——ATA/ATB/ATD 自动确认
关注码头/泊位级时效（ETA/ETB/ETD、装卸时长、船闸等位）可用"物流场景航次时效性服务"，联系商务开通

场景二：船队实时监控大屏#

适用对象：船公司、船管公司、租家。
场景描述：把自有或租赁船队的实时位置集中呈现在海图大屏上，7×24 小时掌握全队动态。查询模式需要不停轮询，既耗额度又有延迟；推送模式下船讯网每 10 分钟把全队船位 POST 到你的服务端，前端只管渲染。叠加电子围栏（进出场预警）、信号消失提醒（AIS 失联）、航速异常（超速/降速）三类事件，即构成完整监控闭环。大屏长时段轨迹展示建议开启轨迹抽稀（isVacuate=true）。
推荐接口组合：
实时船位推送——10 分钟周期推送（船队上限 1000 艘）
船队管理：创建船队 AddFleet、船队船舶增加 AddFleetShip 等（见附录 A 第 9 板块）
船舶历史轨迹查询 GetShipTrack——轨迹回放
区域监控推送 AddArea——电子围栏
船舶 AIS 信号消失事件推送、船舶航速异常推送
海图 GIS 平台（船位展示服务、历史轨迹服务）

场景三：港口运营与拥堵分析#

适用对象：港口调度、码头运营方、航运分析机构。
场景描述：实时掌握"港里停了多少船、锚地等了多少船、未来几天还有多少船要来"，是港口资源调度和拥堵研判的基础。分别查询当前靠泊、当前到锚、未来预抵三个船舶清单，按船型/船籍筛选后做统计；再叠加港口挂靠历史船舶数据，可以分析港口吞吐节奏、平均在港时长等指标。官方示例见港口运力监控与找船。
推荐接口组合：
港口当前靠泊船查询 GetBerthShips（高级服务）
港口当前到锚船查询 GetAnchorShips（高级服务）
港口预抵船舶查询 GetETAShips（高级服务，按 port_code + 时间窗 + 船型查询）
港口信息查询 SearchPort——先拿到港口五位码
港口挂靠历史船舶 GetPortofCallByPort——吞吐与在港时长分析
注意：做拥堵统计时开启 search_type 屏蔽"僵尸船"（港内变更 MMSI 后离港的船，见 Q70）。

场景四：货运异常预警中心#

适用对象：货主、贸易商、物流风控团队。
场景描述：大宗海运的风险不只来自台风巨浪，更多是"静悄悄"的异常——船莫名降速（机械故障或扣船前兆）、AIS 信号消失（关闭应答器，走私/制裁规避常用手段）、与不明船舶贴近并航（海上过驳/盗抢风险）、台风逼近航线（货损与延误）。以事件推送为触发源建立"事件自动找人"机制，分级预警、联动处置。官方完整示例（含分级预警与处置台设计）见货运异常预警中心。
推荐接口组合：
船舶 AIS 信号消失事件推送——失联及恢复事件
船舶航速异常推送——超速/低速
船舶搭靠事件推送——贴近并航
周边船舶查询 GetSurRoundingShip——事件位置 10 海里内船舶核验
船舶历史轨迹查询 GetShipTrack、船舶互相搭靠记录查询 SearchshipApproach——事后核对
获取全球台风列表 GetAllTyphoon + 获取单个台风信息 GetSingleTyphoon——台风态势

场景五：贸易流与货源分析#

适用对象：贸易商、研究机构、数据分析师。
场景描述：通过船舶挂靠记录里的"到港吃水/离港吃水"差值推断装卸货（满载进、空载出），结合港口挂靠历史船舶的上一港/下一港链条还原运输路径，再叠加船舶档案的载重吨、船型、经营人信息，即可构建大宗商品贸易流向与运力分布分析。
推荐接口组合：
船舶历史挂靠记录 GetPortofCallByShip——单船挂靠链（含吃水）
港口挂靠历史船舶 GetPortofCallByPort——含上一港/下一港，构建航线链条
船舶档案查询 SearchShipParticular——船型、载重吨、经营人
船舶船籍查询 GetShipRegistry——船旗国统计

场景六：航运金融与保险风控#

适用对象：船东互保协会（P&I）、保险公司、海事律所、银行租赁。
场景描述：保险与风控关注"这条船历史上做过什么、出过什么事、现在在哪"。历史轨迹用于行为回溯与事故还原；搭靠记录用于识别异常海上作业（过驳、盗抢）；船舶档案含船级社、P&I 保赔协会信息；档案扩展服务进一步提供 PSC 检查记录、事故记录、商业变更历史与安全管理证书，支撑核保定价与理赔调查。
推荐接口组合：
船舶历史轨迹查询 GetShipTrack——行为回溯（注意默认只能查 1 个月内，更久需联系商务）
船舶互相搭靠记录查询 SearchshipApproach——异常海上作业
航行警告查询 GetNavWarning、获取全球台风列表 GetAllTyphoon——风险区域
船舶档案查询 SearchShipParticular——船级社、P&I
档案服务扩展（GetShipPSC / GetShipBusinessHistory / GetShipAccidents / GetShipSMC）——PSC 检查、事故、商业变更、SMC 证书

场景七：航线规划与油耗/成本测算#

适用对象：航运调度、租船经纪人、燃油供应商。
场景描述：在报价或派船阶段，先算出两港之间的标准航程与航线走向，叠加气象数据（风、浪、洋流）评估避让成本，再结合精确 ETA 与船队平均航速测算航次成本、油耗与到港时间。航线规划适用于远距离海上航行，不建议港区附近使用。
推荐接口组合：
港到港航线规划 PlanRouteByPort——五位码入参，输出总海里+路径点，支持 avoid 指定绕航节点（绕航节点清单）
点到点航线规划 PlanRouteByPoint——任意经纬度起终点
预计到达时间 ETA 查询 GetSingleETAPrecise——mmsi + port_code（+ speed）计算剩余航程与 ETA
实时气象数据 CurrentWeather / 未来气象预报 FutureWeather——避浪绕航评估

场景八：海上风电与工程作业监控#

适用对象：海上风电运营商、海洋工程公司、施工方。
场景描述：风电场、钻井平台等海上设施最怕船舶闯入作业区与锚害。以设施坐标为核心建立"三级防御圈"（观察/预警/警戒），用周边船舶查询做由近及远扫描，结合航速航向推算最近会遇点（CPA/TCPA）评估碰撞风险；同时自建电子围栏接收进出事件推送，叠加 100 米高度风数据服务风机运维窗口期判断。官方完整示例见海上设施监管及其四个子场景：监管区域与事件推送、设施周边安全监控、偏航识别与轨迹回放、气象海况与航行警告。
推荐接口组合：
周边船舶查询 GetSurRoundingShip——10 海里、由近及远排序
区域创建 AddArea + 区域监控推送内容——电子围栏与进出事件
船舶航速异常推送
实时气象数据 CurrentWeather——含 100 米高度风（风电/平台场景）
航行警告查询 GetNavWarning——12 类警告区域

场景九：只想在地图上展示船#

适用对象：做可视化大屏、小程序、官网地图的开发者。
场景描述：不需要复杂业务逻辑，只想把船画在图上。直接用船讯网海图 GIS 平台（基于 Leaflet 的封装库），开通 key 即可访问在线标品海图，配合船位数据接口即可完成"船在图上动"的最小实现；若要叠加到高德/百度等国内底图，注意坐标纠偏。
推荐接口组合：
海图 GIS 平台开发（快速入门、船位展示服务）
区域船舶查询 GetAreaShip——当前视口内的船
叠加国内底图需做坐标系转换（坐标系转换指南）

场景十：货物运输防盗与视频监控#

适用对象：货主、贸易商、保险公司、航运物流企业。
场景描述：货物在夜间靠泊或锚地等待期间存在被盗风险。在货舱、甲板等关键位置安装支持萤石云协议的摄像头，AI 自动识别设备离线、人员入侵、摄像头遮挡、疑似偷盗（携带装载容器、推铲工具、管线设备接触、小船搭靠）等事件并实时告警，配合 AIS 搭靠事件双重验证。官方示例见视频监控场景应用指南。
推荐接口组合：
视频监控服务概述、接入指南、API 服务说明
设备状态/实时视频/历史回放/AI 事件接口（见附录 A 视频监控板块）
船舶搭靠事件推送——小船搭靠交叉验证

场景十一：用 AI 大模型/智能体快速构建应用#

适用对象：想用自然语言直接调用船舶数据的应用开发者、AI 产品团队。
场景描述：不写代码或少量代码，让 AI 助手通过 MCP 协议直接调用船讯网的查询工具（船位、航线、气象等），适合快速原型、内部风控问答、运营助手等场景；也可以直接使用船讯网预置的行业智能体（运力资源、船舶风控、运输规划、航次时效预测等）。详见AI 大模型接入 MCP 服务与AI 智能体应用。

第三部分 按业务板块的常见问题#

一、服务通用问题#

Q30：客户防火墙需要加白名单，服务的 IP 地址和端口是什么？#

查询类 API 与各类推送服务部署在不同服务器集群上，且定制类接口可能使用独立的服务器资源，IP 会随资源调整而变化。出于安全与管理考虑，本文档不直接罗列服务器 IP。需要配置防火墙白名单时，请联系对接的商务人员获取当前生效的服务器 IP 清单，端口固定为 HTTP 80 / HTTPS 443。商务联系方式见附录 D。

Q31：服务质量指标如何？#

平均响应时间 300 毫秒以内；可用性 99.9% 以上；有固定数据灾备中心；支持 HTTPS 加密传输。并发默认限制：一个 key 下所有服务共用每分钟 600 次（1 秒 10 次），特殊情况可申请升级并发。

Q32：接口请求频率过高被限制怎么办？#

船位、轨迹接口默认 1 秒 10 次、1 分钟 600 次，其余接口共用次数。超限会被暂时限制：停止调用 3 分钟后自动解除，期间检查调用逻辑是否有变动（常见原因：程序死循环重试、多实例并发未做限流）。官方场景化开发示例中给出了调用频率建议与降级策略，高并发系统设计前建议阅读。

Q33：返回"查询船舶数量/次数已超限"怎么办？#

先确认 key 是否泄露（泄露则锁 IP、换 key）；没有泄露则确认是否需要清零或加购额度。当前用量在控制台「权限查看」和「流量趋势」页面可查。

Q34：返回提示 Sensitive 是什么意思？#

该船舶为敏感信号，有可能被套牌。需客户提供证书、船舶类型证据，验证后可调整（status 400，见服务码返回说明）。

Q35：怎么给 key 设置 IP 白名单？#

控制台找到对应 key，在【访问限制】里设置 IP 白名单，可防止 key 泄露后被其他用户盗用。注意：设置了过窄的白名单后，公司出口 IP 变更会导致请求被拒，需同步更新。

Q36：时间参数用什么格式？#

大多数接口的时间参数用 **Unix 时间戳，秒级（10 位）**而非毫秒（13 位）；开始时间必须是历史时刻。例外（务必对照接口文档）：
历史气象记录 HistoryWeather：yyyy-MM-dd HH:mm:ss 格式字符串
航行警告查询 GetNavWarning：yyyy-MM-dd HH:mm 格式字符串
国内/全球潮汐详情：start_date/end_date，yyyy-MM-dd 格式
档案扩展服务（PSC/事故记录等）：yyyy-MM-dd 格式

Q37：单次查询的数据量限制有哪些？#

多船位置查询 GetManyShip：mmsis 逗号分隔，一次最多 100 艘
区域船舶查询 GetAreaShip：官方建议单次区域控制在 1°×1° 以内，JSON 格式单次约可返回 2600 条、二进制格式约 8000 条，超出用 scode 分页（见 Q49）；另有区域船二进制解析说明
船队上限 1000 艘；推送每包 50 艘
船舶历史轨迹查询 GetShipTrack：默认只能查 1 个月以内，更久联系商务开通
历史气象记录 HistoryWeather：单次查询周期不超过 1 个月，最多查询历史三年

Q38：在线调试在哪里？怎么用？#

每个接口文档页面都有"在线调试"入口（如单船位置查询页内），无需写代码即可发送真实请求、查看返回样例。注意必须先创建自己的 Key 并开通对应权限，直接用文档里的演示 Key 会返回 status 14（见 Q8）。

Q39：常用入口和联系方式？#

API 开发文档：https://apidocs.shipxy.com/
API 控制台：https://api.shipxy.com/v3/console/overview
海图 GIS 开发示例：https://api.shipxy.com/h5s/api/3.5/demo/#a1_0 ；场景示例：https://api.shipxy.com/h5s/api/3.5/sample/
商务：support@shipxy.com；技术支持：service@shipxy.com；电话：400-010-8558；控制台商务入口：https://api.shipxy.com/v3/console/support

二、船舶查询与船位（AIS）#

Q40：船舶查询返回状态码 255 是什么意思？#

航行状态码 255 代表船舶 AIS 设备未更新上报状态信息，与设备类型和船员填写规范有关。完整航行状态编码见官方航行状态对照表。

Q41：船在船讯网页面上还在更新，接口却查不到？#

网页可能用船名查询并自动匹配最新 MMSI，接口用 MMSI 入参。船换 MMSI 后旧号查不到。解决：用船名（未变更前提下）通过船舶模糊查询 SearchShip 找到最新 MMSI 再查。

Q42：船有更新但查不到数据怎么办？#

先对照单船位置查询文档检查返回状态；返回正常但缺数，可能是卫星权限、AIS 设备问题、敏感船类型等原因，联系船讯网核实。

Q43：船舶搜索、单船、多船查询的区别？#

单船位置查询 GetSingleShip：一条船的详细信息
多船位置查询 GetManyShip：多条船详细信息，mmsis 逗号分隔，上限 100 条
船舶模糊查询 SearchShip：返回简单信息（船名、MMSI、IMO、呼号、数据来源、船型），可用 max 控制条数（最多 100，建议 ≤10），按关联度+船位更新时间排序；该服务不限调用次数，开通权限后可多次调用
船队位置查询 GetFleetShip：一次查整个船队，需先创建船队（见 Q47）
适用场景提示：固定跟踪的船队用多船/船队查询；船舶经常变更（如临时租船）用单船查询；需要很高更新频率推荐改用实时船位推送。

Q44：权限怎么计次？#

单船/多船/船队船底层权限是同一套。一次查多条按船舶数量计次：v3 查 5 条计 5 次，v2 计 1 次（历史遗留，建议升级 v3，参见标准 API 服务说明）。

Q45：多船查询的 mmsis 参数怎么传？为什么报参数错误？#

GetManyShip 的 mmsis 参数用英文逗号分隔多个 MMSI，一次最多 100 个。常见报错原因：用了中文逗号、混入空格、超过 100 个、包含非 9 位数字。示例：mmsis=413961925,477232800,477172700。

Q46：用 IMO 查询能查到什么？#

船舶模糊查询 SearchShip 以 IMO 作为输入时，返回该 IMO 编号下曾经使用过的所有 MMSI 记录——船舶买卖或租赁环节变更 MMSI 后，旧 MMSI 依旧有记录；用船名查询时返回该船名所有历史使用船舶信息。区分目标船时参考 AIS 最新上报时间取最新的记录。

Q47：船队位置查询的 fleet_id 从哪来？#

GetFleetShip 的 fleet_id 是 UUID 格式的船队编号（如 3e42a3db-6cdf-4c62-9473-8ad00348d646），通过创建船队 AddFleet 或查询船队 GetFleet 获得。只能查询当前 key 下创建的船队——换了 Key 就查不到旧船队，需要在新 Key 下重建。

Q48：区域船舶查询查不到或数据缺失？#

逐项排查（GetAreaShip 文档）：
1.
坐标格式：region 参数为 lng,lat-lng,lat-…（先经度后纬度、逗号分隔点内坐标、减号分隔多个点）
2.
顶点必须按顺时针或逆时针依次输入，坐标点必须超过 2 个
3.
范围是否超出购买时设定的权限区域（超出后无法返回数据）
4.
区域过大超限：官方建议单次 ≤1°×1°；JSON 单次约 2600 条、二进制约 8000 条，超出分割区域或用 scode 翻页

Q49：大区域怎么拿全数据？（scode / continue 机制）#

GetAreaShip 首次请求返回 scode（开头）和 continue（末尾）：continue=1 表示还有数据，带 scode 再次请求，直至 continue=0。翻页时区域范围和 key 不能变，且须在 10 分钟内取完（超时 scode 重置）。二进制返回格式（output=0）的解析方法见官方区域船二进制解析说明。

Q50：船明明在区域内却不返回？#

GetAreaShip 只返回 2 小时内有上报的船舶（超过 2 小时未报视为已离开，无法判定是否还在区域内）；默认屏蔽航标网位仪（可用参数控制添加）；默认屏蔽敏感船（政府或执法单位等可申请访问）；不支持查历史时间点数据。如需更大范围或更高频率，船讯网支持定制 TCP/IP、Kafka 等推送方式接入（联系商务）。

Q51：周边船舶查询怎么用？#

GetSurRoundingShip 以目标船当前位置为圆心，返回半径 10 海里内全部船舶（含目标船自身），按由近及远排序，按 MMSI 入参；不可指定区域和半径（防爬取），每 5 分钟限请求一次。典型场景：海上施工安全监控、避碰预警、应急救援。

Q52：通过 MMSI 查船舶档案没有数据或与实际不符？#

先看有没有 IMO——只有 IMO 船才有档案（SearchShipParticular，IHS 劳氏数据，每周更新）。有 IMO 但 MMSI 对不上：船可能改了 MMSI 尚未通过劳氏授权审核，有滞后，劳氏更新后船讯网同步。档案内容包括基础信息（载重吨、经济航速等）、注册信息（船旗国、船级社、P&I）、集团方/管理者/经营者/DOC/建造者、主辅机信息等。

Q53：除了基础档案，还能查船舶的 PSC 检查、事故记录吗？#

可以，用档案服务扩展，包含四个接口：
GetShipPSC：PSC 港口国监督检查记录
GetShipBusinessHistory：商业变更历史（空字段表示该项无变更）
GetShipAccidents：事故记录（含事故类型英文术语对照）
GetShipSMC：安全管理证书（ISM 体系）
均以 IMO 为入参；PSC 与事故记录的时间参数 start_time/end_time 用 yyyy-MM-dd 格式。

Q54：怎么做船籍匹配？#

用国家字段匹配即可（不必用国家编码字段），接口为船舶船籍查询 GetShipRegistry。船籍按 MMSI 前三位匹配；注意船籍国≠船旗国，个别航标网位仪可能判错。

Q55：船位精度多少？为什么有时偏差大？#

GPS 正常 5-10 米，北斗+GPS 可达 3-5 米。卫星遮挡时会切换到运营商基站三角定位，产生偏差，属正常现象。

Q56：模糊查出多条结果，怎么确定目标船？#

变更信息会保留一段时间，取静态信息更新时间最新的那条（见 Q46）。

三、历史轨迹与历史行为#

Q57：轨迹查询查不到数据？#

排查（GetShipTrack 文档）：① 返回状态是否成功；② 时间范围是否在权限内；③ 时间戳是否秒级 10 位；④ 开始时间是否历史时刻。正常但无轨迹：该时段未有效航行或关闭 AIS。

Q58：为什么默认只能查最近 1 个月的轨迹？#

GetShipTrack 服务默认只能查询 1 个月以内的船舶轨迹；需要查询更久之前的轨迹记录，请联系商务开通。历史数据最早可回溯到 2012 年。

Q59：3 月轨迹查不到，最早只能查到 6 月？#

船在 3 月换了 MMSI。用当时船名（未变更的静态信息）通过船舶模糊查询 SearchShip 搜出对应时期的 MMSI 再查。

Q60：轨迹与实际路径不一致？#

核对 MMSI 是否同一艘（存在他船冒用 MMSI 情况）；确认有误联系船讯网。

Q61：某时段轨迹点缺失？#

常见原因：恶劣天气、地形遮挡、军用设施/电厂/核厂附近、设备断电或供电不足、锚泊时发射功率自动降低、设备老旧、人为关闭、硬件故障。

Q62：怎么判断轨迹数据来源？#

data_source=0 岸基（或船基），=1 卫星（见单船位置查询返回说明）。

Q63：轨迹抽稀是什么？什么时候开？#

Douglas-Peucker 算法保留关键轨迹点，减少 30%-70% 数据量，参数 isVacuate（true/false，GetShipTrack）。大屏显示、移动端、长时段查询、趋势分析开 true；精确距离计算、事故调查开 false。

Q64：搭靠记录查询怎么用？approach_zone 参数是什么？#

SearchshipApproach（高级服务）按 MMSI + 时间段查询船舶搭靠行为，返回搭靠船舶详情、位置、坐标、起止时间；判定口径为两船贴近停靠或并排行驶超过 5 分钟。参数 approach_zone 区分搭靠发生区域（港口/锚地/其他，取值见接口文档参数表）：加油客户关注锚地内搭靠，物流客户只关心航行中搭靠。此服务为高级服务，需联系商务开通权限。

四、挂靠记录与港口#

Q65：港口五位码查不到？#

船讯网五位码与网络上查的可能不一致。先用港口信息查询 SearchPort（keywords + max）以港口中英文名查一次，拿到船讯网五位码，再查靠泊/到锚/预抵。

Q66：港口名查不到？#

可能查的是某大港的子港，换大港名称在SearchPort 里试。

Q67：挂靠怎么判定？#

船舶驶入港口地理围栏 + 减速至近乎停留 + 持续足够时间（约 10 分钟）= 生成挂靠记录。直接穿过、内河直接通过、体系内无该港口（围栏缺失）不算挂靠。AIS 无"停留"标志，系统按两时点经纬度偏移量判断停留/漂航。相关接口：船舶历史挂靠记录 GetPortofCallByShip、船舶当前挂靠信息 GetShipStatus。

Q68：靠港记录的起止时间过滤哪个字段？#

挂靠时间与查询范围有交集即返回：ata 在 [start,end] 内，或 ata 在 start 前且 atd 在范围内或为空（仍在港）。港口挂靠历史船舶 GetPortofCallByPort 可选按 ATA 或 ATD 过滤。

Q69：靠泊时间/离港时间为 0 是什么？#

靠泊时间=0：到港未靠泊（锚泊等待）；离港时间=0：仍在港。统计在港时长必须处理这两类，直接相减会算错。字段口径见船舶历史挂靠记录。

Q70：当前靠泊里的"僵尸船"怎么处理？#

船在港内变更 MMSI 后离港，旧号永远"停留"在靠泊记录中。原始数据因监管追溯不可删，用 search_type 参数在展示层屏蔽（港口当前靠泊船查询 GetBerthShips：search_type=1 屏蔽僵尸船）：拥堵统计开屏蔽，历史追溯关屏蔽取全量。

Q71：预抵船舶可信吗？预抵接口怎么用？#

预抵完全依赖船员填报的目的港字段（申报型数据），目的港漂移、临时改港频繁，远期预抵可信度有限。港口预抵船舶查询 GetETAShips（高级服务）以 port_code（五位码）+ start_time/end_time（Unix 秒级时间戳，界定未来预抵时间窗）+ ship_type（船型筛选）查询；配套船舶挂靠指定港口记录 GetPortofCallByShipPort 查指定港口挂靠明细。

Q72：客户说的"港口"查不到挂靠？#

认知差异：客户认知的港口在体系内可能是"码头"，无围栏标注。港口 ID 已对外封闭，走五位码；缺五位码反馈数据团队补录。内河港口数据相对薄弱、小码头聚集区精度不足，持续完善中。

Q73：挂靠和搭靠的区别？#

挂靠=船到港停靠记录（挂靠记录接口族）；搭靠=两船贴近并排超 5 分钟（SearchshipApproach）。搭靠有 approach_zone 参数区分港口/锚地/其他：加油客户关注锚地内搭靠，物流客户只关心航行中搭靠。

Q74：吃水数据有什么用？#

到港记一次、离港记一次，差值推断装卸货（满载进、空载出），贸易流分析高价值字段。挂靠记录接口（GetPortofCallByShip）返回到港/离港吃水。

Q75：细分锚地监控怎么做？#

对外到锚结果（港口当前到锚船查询 GetAnchorShips）只到"该港口锚地"层级，更细的锚地划分可定制。通用方案：自建区域围栏（多边形+名称，AddArea）+ 区域监控推送。

Q76：港口板块哪些接口是高级服务？#

港口当前靠泊船查询 GetBerthShips、港口当前到锚船查询 GetAnchorShips、港口预抵船舶查询 GetETAShips 均为高级服务，需申请高级权限（联系商务，控制台支持入口 https://api.shipxy.com/v3/console/support）。[港口信息查询 SearchPort](https://apidocs.shipxy.com/471397856e0) 为标准服务。

五、航线规划与 ETA#

Q77：有几种 ETA？严格区分#

1.
船位查询里的 eta：AIS 设备船员手填，非计算值（GetSingleShip 返回字段）。可能忘记更新、是上一港旧值，系统不修正；格式不统一，大概率目的港时区，准确率不高
2.
精确 ETA 查询 GetSingleETAPrecise（5.3 接口）：系统计算，剩余里程 ÷ 平均航速

Q78：精确 ETA 的计算逻辑？#

剩余里程：航线大数据拟合真实航线，船舶当前位置匹配最近航线取剩余里程（无历史航线依据时按可航航道最短路径法）
平均航速：离港后取当前航次平均、在港取上一航次平均；剔除 3 节以下数据点
约 5 分钟更新一次；不含港口排队时间；船停留时 ETA 持续后延
入参：mmsi + port_code（目的港五位码），可选 speed 指定航速（接口示例）

Q79：5.3 接口 ETA 和船位查询 ETA 不一致？#

前者是推算值，后者是 AIS 设备填报值，来源不同属正常（见 Q77）。

Q80：ETA 能精确到什么级别？#

港口层面，到不了码头泊位。需要码头级时效用"物流场景航次时效性服务"（ETA/ETB/ETD、装卸时长、船闸等位），联系商务开通。

Q81：航线规划有哪两种模式？avoid 参数怎么用？#

点到点 PlanRouteByPoint：start_point + end_point（两个坐标点），或 start_point + end_port_code（起点坐标 + 终点港五位码）
港到港 PlanRouteByPort：start_port_code + end_port_code（两个五位码），可加 avoid 参数指定绕航节点 ID（如 avoid=11），绕开特定海峡/水道——绕航节点编号与名称对照见官方绕航节点清单
两个接口都输出航线总里程（海里）与路径点坐标。适用于远距离海上航行（航次预算、油耗评估、偏航预警、电子围栏设置），不建议港区附近使用。

六、气象天气#

Q82：台风接口的 time 是什么时间？#

UTC 时间，使用需 +8 转北京时间。台风数据来自中央气象台，返回代码与中英文名（如"罗莎/KROSA"），展示自选。

Q83：台风数据怎么查？为什么要查两次？#

按官方设计是两步查询（6.2 全球台风）：
1.
GetAllTyphoon（高级服务）：获取近三年全球台风列表（位置、走向、风速、风级、半径等），只用 key 调用
2.
GetSingleTyphoon：从列表返回中取台风 id，用 typhoon_id 查单个台风的详情数据
注意：风圈半径单位为公里。

Q84：各气象服务覆盖范围？#

实时气象/未来气象（新全球气象）：全球，0.08° 网格
单点海洋气象 GetWeatherByPoint：全球，0.25° 网格
海区气象 GetWeather：只国内（中央气象台），只需 key 入参
国内港口潮汐 / 全球港口潮汐：分国内/全球两套接口
暂无内河气象，聚焦海上

Q85：更新频率？#

单点海洋气象（0.25°）：一天 2 更，间隔 6 小时，预报未来 7 天
海区预报：一天 4 更，间隔 12 小时，预报未来 72 小时
新全球气象（0.08°）：1 小时一包；大气未来 7 天、海洋未来 5 天
历史气象：近三年，只能查 24 小时以前
旧版气象接口只有预测，只能查未来 7 天

Q86：海区预报还是单点气象？#

趋势展示用海区（南海、东海等标准海区，海区编号对照见官方海区对照表）；具体节点用单点（经纬度查该点气象）。海区预报返回的"沿岸"分区（如山东半岛东部沿岸）是气象局业务定义，比标准海区更细。

Q87：新全球气象的几个专业概念？#

CurrentWeather / FutureWeather（高级服务）数据精度为 0.08°×0.08° 每网格，请求坐标会自动吸附到最近格点；逐小时数据，未来气象支持 7 天预报。波高为谱显著波高（1/3 有义波高）；海浪=风浪+涌浪能量叠加；10 米风≈地表风（通航/海面设施），100 米风更大（风电/钻井平台场景）。

Q88：潮汐查询的 port_code 是港口五位码吗？#

不是。港口潮汐观测站和船讯网中的港口不是一个概念：查询潮汐观测站列表 GetTides（国内）/GetGlobalTides（全球）返回的是观测站自己的 port_code（数字编号），查详情（GetTideData / GetGlobalTideData）时要用观测站编号，不能用港口五位码。详情接口时间参数为 start_date/end_date（yyyy-MM-dd）。潮汐高度按各港口潮汐基准面计算，不同港口基准面不同。

Q89：历史气象怎么查？时间格式是什么？#

HistoryWeather 按经纬度查单点历史气象：start_time/end_time 用 yyyy-MM-dd HH:mm:ss 格式字符串（与多数接口的 Unix 时间戳不同，注意区分）；单次查询周期不超过 1 个月，最多查询历史三年数据；只能查 24 小时以前的数据。

七、海事数据（航行警告）#

Q90：航行警告数据来源和频率？#

中国海事局发布公告，船讯网解析处理并提供覆盖范围经纬度，可直接绘制上图或与船位匹配。每天更新 2 次。内河航行警告（如京杭大运河）需项目定制。

Q91：航行警告接口的参数怎么传？覆盖范围是什么形状？#

GetNavWarning 的 start_time/end_time 用 yyyy-MM-dd HH:mm 格式字符串；返回包含 12 类警告（禁止锚泊、禁航、军事演习等），覆盖范围支持**多边形（range_points 经纬度点串）与圆形（圆心+radius_nm 海里半径）**两种形状。航标相关数据可配合官方航标类型对照表解读。

八、海图应用与 GIS#

Q92：海图怎么接入？#

用海图 GIS 平台封装好的开发示例（https://api.shipxy.com/h5s/api/3.5/demo/#a1_0 ），平台基于 Leaflet，开通 key 即可访问在线标品海图。从注册到接入的完整流程见官方快速入门，平台总览见海图 GIS 平台开发。

Q93：海图数据来源与标准？#

C-MAP 数据，遵循 S-57 交换标准与 S-63 加密规范。要素含海岸线、助航标志、航行障碍物、水深线、锚地、海上作业平台等（见地图引擎基础）。

Q94：坐标系与纠偏？#

WGS84。用 GIS 平台示例不需纠偏；海图不纠偏，卫星图和国内地图需纠偏（WGS84↔GCJ-02）。平台提供 gcj_encrypt/gcj_decrypt 等方法，完整转换说明见官方坐标系转换指南；海图模式下中国沿海区域使用 GCJ-02，注意区分。

Q95：有原始水深数据吗？#

没有，水深融合在底图上，仅供参考。

Q96：更新频率与部署方式？#

全球海图年度更新（另有付费月更新版）；卫星图/地图年度更新。API 海图只能在线用；私有化可定制：按范围导出为通用瓦片（Z/X/Y 金字塔目录，或 MBTiles/PMTiles 单文件库），详见私有化部署开发指南及配套实践文档（私有化地图加载绘制、船舶与轨迹绘制实践、气象图层效果绘制）。

Q97：能一次定位多艘船吗？#

不能同时定位，但可同时显示；需要定位切换开发时嵌套循环。

Q98：能叠加到百度地图吗？#

可以，天地图/高德/百度都行，但国内底图需纠偏（见 Q94）。

Q99：自动刷新频率？#

缩放 13 级前 1 分钟、13 级后 15 秒；单船每次查询触发。暂不支持自行配置。

Q100：海图多出网格线？#

浏览器缩放比例导致，瓦片按标准 xy 排列，浏览器缩放时有位置误差。

Q101：前端直连 API Key 有安全问题怎么办？Vue 项目能用吗？#

后端代理：Key 不应暴露在前端页面，推荐后端做代理转发，官方给出完整方案见API Key 后端代理接入
Vue 接入：平台提供 Vue 项目接入指南（7.7）
容器高度为 0 / 页面空白：地图容器必须显式设置高度（快速入门 FAQ）；本地 file:// 协议打开页面会有跨域与资源加载问题，建议用本地 HTTP 服务调试
相关进阶文档：船位展示服务、历史轨迹服务、图层与气象服务、航线绘制与区域回放服务

九、监控推送服务#

Q102：推送服务整体机制？#

分固定周期推送（实时船位、动态 ETA，各 10 分钟/次）和事件触发推送（区域围栏、航速提醒、到离港、信号消失、搭靠）。基于船队+订阅管理，新版 API 提供完整船队/船舶/订阅增删改查接口，可全部集成到客户自有系统（老版本必须登录控制台操作）。

Q103：想把船队/区域/订阅管理集成到自己系统里，有哪些接口？#

三组管理接口（均为标准 HTTP 接口，可编程调用）：
船队管理（9.1）：创建船队 AddFleet、更新船队信息 UpdateFleet、查询船队 GetFleet、删除船队 DeleteFleet、船队船舶增加 AddFleetShip、船队船舶批量更新 UpdateFleetShip、船队船舶删除 DeleteFleetShip
区域监控（9.2）：区域创建 AddArea、区域更新 UpdateArea、区域查询 GetArea、区域删除 DeleteArea、区域监控推送内容（推送数据格式说明）
航速提醒订阅（9.3）：新增船舶订阅 SubShipAlertOfSpeed、删除订阅 UnsubShipAlertOfSpeed、查询订阅列表 SearchSubShipAlertOfSpeed

Q104：回调收到的是 GET 而不是 POST？#

回调地址是 http:// 且服务器 301 重定向到 https:// 时，POST 会被降级为 GET。回调地址直接配 https:// 即可（推送数据格式见区域监控推送内容等各推送说明页）。

Q105：船队容量与推送批量？#

船队增删改查一次可调整 1000 艘，单船队上限 1000 艘；推送每包 50 艘分批，几秒内推完。新加的船要等下一个 10 分钟周期才开始推。

Q106：到离港推送失败怎么恢复？#

可绑定手机号，失败后短信提醒，点【重新推送】恢复。失败机制：两小时内按 4 分钟频率重推；超两小时触发封禁提醒并降频，需手动重启。推送字段（ATA/ATB/ATD）说明见船舶到离港事件推送。

Q107：怀疑漏推？#

先查客户系统有没有拦截（多数是自己系统拦的）；配置 url 后无报文，看事件发生在配置前还是配置后——只有配置后的事件才推。

Q108：电子围栏点位超限？#

大型区域栅格点位可能超 1000 个，需删减（手动调整边界锯齿点）。100 点位内用 GET，超 100 用 POST（AddArea）。

Q109：改了 url 还往旧地址推？#

url 有两处：【监控区域管理】的 url 针对单个区域（优先级高）；【推送 url 管理】是全局统一地址。两处都绑时优先单区域地址，改掉旧地址即可（区域更新 UpdateArea）。

Q110：主动获取历史事件查不到？#

前置条件与限制：key 需订阅且设置船舶列表；只能查近 7 天；时间跨度 ≤30 分钟；已推送的事件查不到；订阅前发生的事件不支持。主动获取卡的是数据更新时间（离港确认有延迟），适合定期扫描增量更新；查历史挂靠用船舶历史挂靠记录 GetPortofCallByShip。

Q111：信号消失推送是什么？#

订阅船超 15 分钟未上报 AIS 即推送信号消失事件（9.7 推送，含恢复事件）。原因可能是关设备或基站未覆盖，系统只记录不判断，需自行分析。

Q112：怎么判断推送是否正常？#

船位/ETA 推送 10 分钟一次，长时间收不到即异常；区域推送可在控制台比对成功/失败记录时间；到离港多次失败会短信通知并需手动重启。

Q113：区域监控推送的内容里 event_type 是什么？#

区域监控推送内容：event_type 标识事件类型——1=到达（进入区域）、2=离开（驶出区域）、3=疑似穿越。区域创建时可选择筛选类型（船型等）自动跟踪区域内船舶进出；监控固定船队则需先把船加入船队（见 Q103）。

十、数据字段与数据质量#

Q114：AIS 数据经过哪些处理？#

原始报文 → 数据清洗（过滤乱码异常）→ 标准化（坐标系/时间戳/时区统一）→ 时空索引 → 目的港标准化（匹配标准港口名+五位码）→ 中文船名匹配（拼音规则自动生成，如 wanhongyuan→"皖宏远"，错误可反馈人工修订）。

Q115：静态/动态/航程数据更新周期？#

动态数据秒/分钟级；静态数据季度/年度级（船型、船长、IMO 等固有属性若频繁变更，大概率数据匹配错误）；航程数据随靠离港更新。分析时区分周期，避免新旧混用。

Q116：坐标异常怎么甄别？#

经纬度超出范围（纬度 ±90、经度 ±180）、固定不变的漂移坐标、落在陆地的坐标均为脏数据，需过滤。

Q117：SOG 为 0 时 COG 还有意义吗？#

没有。运动参数要关联校验：锚泊状态下航速异常偏高大概率是设备故障。

十一、视频监控服务#

Q118：视频监控服务是什么？能做什么？#

船讯网面向航运物流行业的船舶远程视频监控解决方案：在船上部署支持萤石云协议的海康威视摄像头，结合 AI 智能识别，实现实时查看船上画面、历史录像回溯、定时截图留存，以及异常事件自动预警（设备离线、人员入侵、摄像头遮挡、开关舱门、疑似偷盗——携带装载容器、推铲工具、管线设备接触、小船搭靠等）。服务介绍见视频监控 AI 识别预警服务。

Q119：怎么接入视频监控服务？#

四步（详见接入指南）：① 硬件准备（支持萤石云协议的海康摄像头、4G/5G 或卫星网络、12V 供电）；② 注册船讯网账号并在控制台创建应用 Key；③ 设备入网与绑定（用设备序列号、验证码与船舶 MMSI 关联）；④ 联系商务开通视频监控权限后接入 API 与事件推送。

Q120：视频监控有哪些接口？频率限制？#

接口清单与格式见视频监控 API 服务说明（基地址 https://api.shipxy.com ，认证与通用返回结构同其他服务）：
设备状态：GetShipDevicesStatus（按 MMSI 查设备在线/离线）
实时视频：GetVShipPreview；历史视频：GetVShipPlayback；定时截图：GetVShipImgs
AI 事件：GetVShipAiEvents（疑似偷盗等事件记录）
事件订阅：VShipSubscribeSet / VShipSubscribeDel / VShipSubscribeQuery
视频下载：AddPlaybackRecordTask（创建任务）、PlaybackRecordTaskQuery（任务查询）、SetPlaybackRecordTaskCancel（取消任务）、GetPlaybackDetail（下载详情）
频率限制（详见服务 FAQ）：设备状态/实时视频每秒 5-10 次（按套餐）；历史视频/截图查询每秒 1 次；事件推送不限制；视频下载任务创建每分钟 5 次。

Q121：一个 Key 能同时用于视频监控和其他船讯网服务吗？#

可以，控制台创建的应用 Key 权限互通，可同时用于视频监控和船位查询、航线规划等服务。但视频监控服务需要单独开通权限，创建 Key 后需联系商务开通（见服务 FAQ）。

Q122：视频监控怎么收费？#

基础视频查看按设备数量收取服务费；历史视频下载按流量（分钟）计费；基础 AI 事件（离线/遮挡/入侵/开关舱门）含在套餐中；疑似偷盗识别需单独开通、按设备计费；电话通知为增值服务。具体价格咨询商务（服务 FAQ）。

十二、AI 大模型与智能体服务#

Q123：什么是船讯网 MCP 服务？#

MCP（Model Context Protocol）是让 AI 大语言模型安全、标准化调用外部工具的开放协议。船讯网 MCP 服务让 AI 助手直接调用船舶位置查询、航线规划、气象查询等工具——不写代码、用自然语言即可获取实时航运数据，适合快速原型、内部问答助手、AI 应用集成等场景。配置接入方法、可用工具清单与 FAQ 见AI 大模型接入 MCP 服务。

Q124：船讯网提供哪些现成的智能体？#

AI 智能体应用提供七个行业智能体：运力资源智能体、船舶风控智能体、运输规划智能体、航次时效预测智能体、船舶安全监控智能体、多式联运协同智能体、大宗贸易态势分析智能体。

Q125：什么场景适合用 MCP / 智能体而不是直接调 API？#

需要快速验证想法、做演示原型，不想写代码
企业内部已经用 AI 助手（支持 MCP 的客户端），想让助手能查船位、算 ETA
面向非技术用户的问答式数据服务（"帮我查青岛港靠泊船"）
生产级系统、高频批量数据需求仍建议直接调用 REST API；两者也可组合（AI 做交互层，API 做数据层）。

附录#

附录 A：API 接口速查表（含英文名与开发文档链接）#

请求形式统一为 https://api.shipxy.com/apicall/v3/<接口英文名>?key=...。标注"高级服务"的接口需联系商务申请高级权限。推送类服务（9.2.5、9.3.4、9.4-9.8）为系统主动 POST 推送，非 HTTP 请求接口。

A.1 船舶查询（板块 1）#

服务接口英文名说明开发文档
单船位置查询GetSingleShip单船实时 AIS 船位与信息https://apidocs.shipxy.com/475744018e0
多船位置查询GetManyShipmmsis 逗号分隔，一次最多 100 艘https://apidocs.shipxy.com/475744019e0
船队位置查询GetFleetShip按 fleet_id 查全队，船队上限 1000 艘https://apidocs.shipxy.com/475744020e0
船舶模糊查询SearchShip名称/MMSI/IMO/呼号模糊搜索；IMO 入参返回历史所有 MMSI；不限次数https://apidocs.shipxy.com/475744017e0
周边船舶查询GetSurRoundingShip目标船 10 海里内船舶，由近及远排序https://apidocs.shipxy.com/475744021e0
区域船舶查询GetAreaShip多边形区域内船舶；scode 翻页；二进制解析说明 https://apidocs.shipxy.com/9454307m0https://apidocs.shipxy.com/475744022e0
船舶船籍查询GetShipRegistry按 MMSI 查船籍注册信息https://apidocs.shipxy.com/475744023e0
船舶档案查询SearchShipParticular劳氏档案：尺寸/吨位/公司/机务等https://apidocs.shipxy.com/475744024e0
档案服务扩展GetShipPSC、GetShipBusinessHistory、GetShipAccidents、GetShipSMCPSC 检查记录、商业变更历史、事故记录、安全管理证书（均以 IMO 入参）https://apidocs.shipxy.com/500532249e0

A.2 港口查询（板块 2）#

服务接口英文名说明开发文档
港口信息查询SearchPortkeywords+max，返回港口五位码https://apidocs.shipxy.com/471397856e0
港口当前靠泊船查询GetBerthShips高级服务；search_type=1 屏蔽僵尸船https://apidocs.shipxy.com/471397857e0
港口当前到锚船查询GetAnchorShips高级服务https://apidocs.shipxy.com/471397858e0
港口预抵船舶查询GetETAShips高级服务；port_code+时间窗+ship_typehttps://apidocs.shipxy.com/471397859e0

A.3 历史行为（板块 3）#

服务接口英文名说明开发文档
船舶历史轨迹查询GetShipTrackMMSI+时间段；默认 1 个月内，更久联系商务；isVacuate 抽稀https://apidocs.shipxy.com/474233611e0
船舶互相搭靠记录查询SearchshipApproach高级服务；approach_zone 区分港口/锚地/其他https://apidocs.shipxy.com/474233612e0

A.4 挂靠记录（板块 4）#

服务接口英文名说明开发文档
船舶历史挂靠记录GetPortofCallByShip单船全部挂靠，含到/离港吃水https://apidocs.shipxy.com/474308123e0
船舶挂靠指定港口记录GetPortofCallByShipPort单船对指定港口的挂靠https://apidocs.shipxy.com/474308124e0
船舶当前挂靠信息GetShipStatus上一港/当前港/下一港https://apidocs.shipxy.com/474308125e0
港口挂靠历史船舶GetPortofCallByPort港口维度挂靠史，含上下港，可按 ATA/ATD 过滤https://apidocs.shipxy.com/474308126e0

A.5 航线规划与 ETA（板块 5）#

服务接口英文名说明开发文档
点到点航线规划PlanRouteByPointstart_point+end_point 或 start_point+end_port_codehttps://apidocs.shipxy.com/475741520e0
港到港航线规划PlanRouteByPortstart_port_code+end_port_code，avoid 绕航节点（清单 https://apidocs.shipxy.com/9061442m0）https://apidocs.shipxy.com/475741521e0
预计到达时间 ETA 查询GetSingleETAPrecisemmsi+port_code（+speed），系统计算精确 ETAhttps://apidocs.shipxy.com/475741522e0

A.6 天气气象（板块 6）#

服务接口英文名说明开发文档
实时气象数据（新全球气象）CurrentWeather高级服务；0.08° 格点吸附，全球https://apidocs.shipxy.com/475752665e0
未来气象预报（新全球气象）FutureWeather高级服务；逐小时，未来 7 天https://apidocs.shipxy.com/475752666e0
获取全球台风列表GetAllTyphoon高级服务；近三年台风列表https://apidocs.shipxy.com/475752661e0
获取单个台风信息GetSingleTyphoon高级服务；按 typhoon_id 查详情，风圈半径单位公里https://apidocs.shipxy.com/475752662e0
查询国内潮汐观测站列表GetTides观测站 port_code 为数字编号，非五位码https://apidocs.shipxy.com/475759820e0
查询单个观测站潮汐详情（国内）GetTideDatastart_date/end_date：yyyy-MM-ddhttps://apidocs.shipxy.com/475759821e0
查询全球潮汐观测站列表GetGlobalTides全球版观测站列表https://apidocs.shipxy.com/475759839e0
查询单个观测站潮汐详情（全球）GetGlobalTideData全球版详情https://apidocs.shipxy.com/475759840e0
海区气象GetWeather中央气象台海区预报，只需 key；海区对照表 https://apidocs.shipxy.com/9061438m0https://apidocs.shipxy.com/475752660e0
单点海洋气象GetWeatherByPoint0.25° 网格https://apidocs.shipxy.com/475752659e0
历史气象记录HistoryWeatherdatetime：yyyy-MM-dd HH:mm:ss；单次 ≤1 个月，近三年https://apidocs.shipxy.com/475752667e0

A.7 海事数据（板块 8）#

服务接口英文名说明开发文档
航行警告查询GetNavWarningdatetime：yyyy-MM-dd HH:mm；12 类警告；多边形/圆形范围https://apidocs.shipxy.com/475669720e0

A.8 监控推送（板块 9）#

服务接口英文名说明开发文档
创建船队AddFleet生成 fleet_id（UUID）https://apidocs.shipxy.com/475752262e0
更新船队信息UpdateFleet-https://apidocs.shipxy.com/475752263e0
查询船队GetFleet-https://apidocs.shipxy.com/475752264e0
删除船队DeleteFleet-https://apidocs.shipxy.com/475752265e0
船队船舶增加AddFleetShip-https://apidocs.shipxy.com/475752266e0
船队船舶批量更新UpdateFleetShip-https://apidocs.shipxy.com/475752267e0
船队船舶删除DeleteFleetShip-https://apidocs.shipxy.com/475752268e0
区域创建AddArea电子围栏；≤100 点 GET、超 100 点 POSThttps://apidocs.shipxy.com/475752271e0
区域更新UpdateArea-https://apidocs.shipxy.com/475752272e0
区域查询GetArea-https://apidocs.shipxy.com/475752273e0
区域删除DeleteArea-https://apidocs.shipxy.com/475752274e0
区域监控推送内容（推送数据格式说明，配合 AddArea）event_type：1=到达 / 2=离开 / 3=疑似穿越https://apidocs.shipxy.com/475752275e0
新增船舶订阅（航速提醒）SubShipAlertOfSpeed-https://apidocs.shipxy.com/475752280e0
删除订阅船舶信息UnsubShipAlertOfSpeed-https://apidocs.shipxy.com/475752282e0
查询订阅船舶列表SearchSubShipAlertOfSpeed-https://apidocs.shipxy.com/475752283e0
船舶航速异常推送（推送数据格式说明）事件触发推送https://apidocs.shipxy.com/475752284e0
实时船位推送（推送数据格式说明）10 分钟周期；每包 50 艘https://apidocs.shipxy.com/475868776e0
船舶到离港事件推送（推送数据格式说明）ATA/ATB/ATDhttps://apidocs.shipxy.com/475867640e0
船舶动态 ETA 推送（推送数据格式说明）10 分钟周期https://apidocs.shipxy.com/475871604e0
船舶 AIS 信号消失事件推送（推送数据格式说明）15 分钟无上报触发，含恢复事件https://apidocs.shipxy.com/475871670e0
船舶搭靠事件推送（推送数据格式说明）事件触发推送https://apidocs.shipxy.com/475871672e0

A.9 海图 GIS 平台（板块 7，SDK 类）#

文档说明链接
海图 GIS 平台开发总览（ElaneMap H5 3.5，Leaflet）https://apidocs.shipxy.com/88879805f0
7.1 快速入门注册到接入四步https://apidocs.shipxy.com/9273651m0
7.2 地图引擎基础地图控制与业务绘制https://apidocs.shipxy.com/9273654m0
7.3 船位展示服务-https://apidocs.shipxy.com/9273658m0
7.4 历史轨迹服务-https://apidocs.shipxy.com/9273668m0
7.5 图层与气象服务-https://apidocs.shipxy.com/9273913m0
7.6 航线绘制与区域回放服务-https://apidocs.shipxy.com/9273933m0
7.7 Vue 项目接入指南-https://apidocs.shipxy.com/9273936m0
7.8 API Key 后端代理接入Key 安全https://apidocs.shipxy.com/9274046m0
7.9 坐标系转换指南WGS84/GCJ-02https://apidocs.shipxy.com/9310088m0
7.10 私有化部署开发指南瓦片导出https://apidocs.shipxy.com/96130656f0

A.10 视频监控（板块 11）#

服务接口英文名说明开发文档
查询船舶视频设备状态GetShipDevicesStatus按 MMSI 查设备在线/离线https://apidocs.shipxy.com/9150632m0
实时视频查看GetVShipPreview预览流https://apidocs.shipxy.com/9150632m0
历史视频查看GetVShipPlayback回放https://apidocs.shipxy.com/9150632m0
定时截图查询GetVShipImgs自动定时截图留存https://apidocs.shipxy.com/9150632m0
AI 事件查询GetVShipAiEvents离线/入侵/遮挡/疑似偷盗等https://apidocs.shipxy.com/9150632m0
事件订阅设置VShipSubscribeSet订阅船舶事件推送https://apidocs.shipxy.com/9150632m0
事件订阅删除VShipSubscribeDel-https://apidocs.shipxy.com/9150632m0
事件订阅查询VShipSubscribeQuery-https://apidocs.shipxy.com/9150632m0
视频下载任务创建AddPlaybackRecordTask每分钟 5 次https://apidocs.shipxy.com/9150632m0
视频下载任务查询PlaybackRecordTaskQuery-https://apidocs.shipxy.com/9150632m0
视频下载任务取消SetPlaybackRecordTaskCancel-https://apidocs.shipxy.com/9150632m0
视频下载详情GetPlaybackDetail-https://apidocs.shipxy.com/9150632m0
服务接入指南-硬件/绑定/接入流程https://apidocs.shipxy.com/9150629m0
场景应用指南-8 个应用场景https://apidocs.shipxy.com/9150634m0
服务 FAQ 与最佳实践-收费/频率/常见问题https://apidocs.shipxy.com/9150642m0

A.11 AI 与智能体服务#

服务说明链接
AI 智能体应用七个行业智能体总览https://apidocs.shipxy.com/90248446f0
AI 大模型接入 MCP 服务协议接入、工具清单、FAQhttps://apidocs.shipxy.com/8961346m0
运力资源智能体-https://apidocs.shipxy.com/9135566m0
船舶风控智能体-https://apidocs.shipxy.com/9136393m0
运输规划智能体-https://apidocs.shipxy.com/9136421m0
航次时效预测智能体-https://apidocs.shipxy.com/9136487m0
船舶安全监控智能体-https://apidocs.shipxy.com/9137335m0
多式联运协同智能体-https://apidocs.shipxy.com/9137330m0
大宗贸易态势分析智能体-https://apidocs.shipxy.com/9137433m0

附录 B：关键概念速查#

概念说明
AIS船舶自动识别系统，船舶通过 VHF 频段自动广播位置等信息的系统
MMSI海上移动业务识别码，9 位数字，船讯网以 MMSI 作为船舶唯一标识
IMO国际海事组织编号，7 位数字，仅远洋船舶具备，有 IMO 才有劳氏档案
五位码船讯网港口唯一标识码，基于国际规范编制，是港口类 API 的关键参数
PortID港口内部 ID，船讯网自有编码，用于关联泊位等内部数据（已对外封闭）
WGS84国际通用地理坐标标准，船讯网 API 坐标系统
Unix 时间戳从 1970 年 1 月 1 日 UTC 零点开始的秒数，API 时间参数的标准格式（秒级 10 位）
抽稀轨迹数据处理技术，按航向变化角度合并直线段轨迹点，减少数据量（isVacuate）
搭靠两条船贴近停靠或并排行驶超过 5 分钟的行为
ETA预计到达时间。AIS 中为船员手填，精确 ETA 为系统计算
岸基 AIS陆上 AIS 接收基站，覆盖沿海约 30-50 海里范围
卫星 AIS通过卫星接收的 AIS 信号，覆盖全球远洋海域
挂靠船舶到港停靠的行为记录，按地理围栏+减速+持续时长判定
电子围栏海图上自定义的多边形区域，船舶进出时触发推送
节/海里1 海里=1852 米；1 节=1 海里/小时≈1.852 公里/小时
GCJ-02国内地图厂商使用的加密坐标系，WGS84 坐标叠加需纠偏
MCPModel Context Protocol，让 AI 大模型标准化调用外部工具的开放协议
CPA / TCPA最近会遇点 / 最近会遇时间，避碰评估指标（客户侧基于船位航速自行推算）

附录 C：开发文档参考清单（对照表与说明）#

文档用途链接
船讯网 API 服务概述服务总览与入口https://apidocs.shipxy.com/
注册与创建应用账号、Key 申请规则https://apidocs.shipxy.com/8961339m0
多语言 SDK 引入Java/JS/Python/C# SDKhttps://apidocs.shipxy.com/8961345m0
标准服务说明服务规范总述https://apidocs.shipxy.com/93963779f0
船舶类型对照表ship_type 代码对照https://apidocs.shipxy.com/9060711m0
服务码返回说明status 状态码含义https://apidocs.shipxy.com/9061428m0
海区对照表海区编号与中英文名https://apidocs.shipxy.com/9061438m0
航行状态对照表navistat 代码对照https://apidocs.shipxy.com/9061439m0
绕航节点清单avoid 参数节点 ID 对照https://apidocs.shipxy.com/9061442m0
航标类型对照表航标类型代码https://apidocs.shipxy.com/9061445m0
区域船二进制解析说明GetAreaShip 二进制返回反序列化https://apidocs.shipxy.com/9454307m0
场景化开发示例API 能力全景与通用技术约束https://apidocs.shipxy.com/95823497f0
大宗物流运输（场景示例）含 3 个子场景https://apidocs.shipxy.com/95824621f0
海上设施监管（场景示例）含 4 个子场景https://apidocs.shipxy.com/95826061f0
官方常见问题页开发文档站内 FAQhttps://apidocs.shipxy.com/9466339m0

附录 D：排查问题通用思路与支持渠道#

遇到接口异常时的通用排查顺序：
1.
对照接口文档（附录 A 各链接）核对请求 URL 和参数名（新旧版本参数不同）
2.
检查返回 status/msg 是否成功（服务码返回说明）
3.
核对时间格式（Q36：多数接口 Unix 秒级 10 位；气象历史/航行警告等接口为字符串格式）与经纬度格式（WGS84）
4.
查控制台权限与额度（https://api.shipxy.com/v3/console/overview）
5.
检查 IP 白名单与回调地址（https://，避免 301 降级 POST 为 GET）
6.
仍无法解决时联系技术支持
支持渠道：
商务咨询（含 IP 白名单清单、高级权限开通、定制服务）：support@shipxy.com，或控制台商务入口 https://api.shipxy.com/v3/console/support
技术支持：service@shipxy.com / 400-010-8558
上一页
区域船二进制解析说明
下一页
AI智能体应用