场景化API 使用示例 · 总览
一、文档目的
本文面向 B 端产品与解决方案团队，基于船讯网开放平台（apidocs.shipxy.com）的标准 API 服务，给出行业大场景的完整落地方案。每个大场景拆分为若干可直接落地的业务子场景，每个子场景给出页面 UI 效果图、业务流程图、调用的接口清单、使用的参数、拿到数据之后的计算过程与业务逻辑，以及每个接口对应的开发文档链接。
面向非开发者（业务视角）：阅读本文档可以建立船讯网 API 的能力地图（能做什么、覆盖哪些业务场景），并基于本文给出的子场景与页面截图快速判断「船讯网能不能解决我的问题」。每个子场景文档都从「这个场景在解决什么业务问题」切入，附带页面截图与业务流程图，再展开到技术细节（接口、参数、计算）。
面向开发者（实现视角）：每个子场景文档都包含可直接拷贝使用的「调用示例」（真实请求 URL 与参数）与「响应示例」（真实 JSON 响应），并给出「计算伪代码」与「最小可运行示例」（Python 代码片段）。基于这些材料，可以在 1–2 天内完成一个端到端 demo。
范围说明：本文只覆盖船讯网可直接调用的标准 API 服务（船舶查询、港口查询、历史行为、挂靠记录、航线规划、天气气象、海图 GIS、海事数据、监控推送九大模块）。示例中所有数据服务仅依赖船讯网接口与客户内部业务数据，不使用任何其他外部第三方数据源。
二、船讯网 API 能力全景
2.1 统一调用方式
标准 API 服务统一为 HTTPS 请求：
https://api.shipxy.com/apicall/v3/{接口英文名}?key=授权码&参数1=值1&参数2=值2
授权码 key 在 船讯网控制台 创建应用后获取。推送类服务（船位、事件、ETA、告警等）由船讯网服务端以 HTTP POST 方式主动推送到客户在控制台配置的接收 URL，无需轮询。
2.2 九大模块与全部接口
接口清单速查：全部接口文档树见 https://apidocs.shipxy.com/llms.txt。
2.3 标识符口径（务必区分）
| 标识符 | 含义 | 注意事项 |
|---|---|---|
mmsi | 9 位水上移动业务标识码 | AIS 类接口的唯一主键 |
imo | 7 位 IMO 船舶编号 | 有 IMO 的船才有完整劳氏档案 |
port_code（港口类） | SearchPort 返回的五位港口码，如 CNTAO | 与潮汐站 ID 不是一回事 |
port_code（潮汐类） | GetTides / GetGlobalTides 返回的观测站 ID | 不能直接把港口五位码传给 GetTideData |
fleet_id | 船讯网控制台船队 ID | 推送服务的订阅单元 |
area_id | AddArea 返回的监管区域 ID | 区域事件推送的关联主键 |
三、场景框架总览
本版在两大行业场景中共落地 13 个业务子场景，其中 6 个为本版新增的分析决策型应用（标注 ★），重点补齐「大屏可视化统计与决策」「业务流中的复杂统计与预测」两类能力。
3.1 大场景一：大宗物流运输智能决策平台
面向煤炭、铁矿石、粮食、原油成品油等大宗商品的海运物流链条，覆盖「市场研判 → 找船订舱 → 航次执行 → 时效与费用管控 → 异常风控 → 能效合规」全链路。
| 编号 | 子场景 | 业务阶段 | 解决的问题 | 形态 |
|---|---|---|---|---|
| A1 | 港口运力监控与找船 | 运力调研 · 租船决策 | 某港现在有多少可用运力？哪条船适合我的货？ | 工作台 |
| A2 | 船队货运跟踪与 ETA | 航次执行 | 我的货现在到哪了？什么时候到港？ | 工作台 |
| A3 | 货运异常预警中心 | 全程风控 | 船出事了没有？降速 / 失联 / 被搭靠 / 台风怎么办？ | 工作台 + 告警 |
| A4 ★ | 大宗航运态势分析与经营决策大屏 | 经营研判 | 区域运力是松还是紧？未来两周到港节奏如何？该不该现在租船？ | 决策大屏 + 预测 |
| A5 ★ | 航次时效预测与滞期费测算 | 航次结算 | 什么时候能靠泊完货？滞期费会亏多少？该怎么谈 laytime？ | 预测 + 费用模型 |
| A6 ★ | 航次能效与碳强度管理 | 合规与成本 | 这条航次碳排放多少？年度 CII 评级会不会掉档？降速能省多少油？ | 测算 + 优化 |
3.2 大场景二：海上设施安全监管与决策平台
面向海上油田平台、海上风电场、LNG 接收站与码头、跨海大桥、海洋牧场等海上设施的防闯入、安全监管与运维调度。
| 编号 | 子场景 | 业务阶段 | 解决的问题 | 形态 |
|---|---|---|---|---|
| B1 | 监管区域与事件推送（总览大屏） | 值班监控 | 谁进了我划的电子围栏？ | 大屏 + 事件流 |
| B2 | 设施周边安全监控 | 近程防御 | 离我设施最近的船有多近？会不会撞上来？ | 工作台 + CPA |
| B3 | 偏航识别与轨迹回放 | 行为研判 | 这条船是正常过境还是冲我来的？ | 研判工具 + 取证 |
| B4 | 气象海况与航行警告 | 环境防御 | 明天能不能作业？台风和军演影响我吗？ | 工作台 |
| B5 ★ | 海上安全态势监管大屏与执法效能分析 | 指挥决策 | 全辖区态势如何？未来 24 小时哪里最危险？执法跟不跟得上？ | 决策大屏 + 预测 |
| B6 ★ | 水域通航密度与碰撞风险预测 | 风险前置 | 这条水道有多挤？什么时候最危险？哪些船对存在碰撞风险？ | 统计 + 风险预测 |
| B7 ★ | 设施运维作业窗口智能排程与船舶调度 | 运维执行 | 多个设施多道工序，哪天哪条船去最合适？天气变了怎么重排？ | 排程优化 |
3.3 子场景之间的数据关系
图中实心箭头为数据流向，箭头标注为该流向传递的核心数据。A4 / A5 / A6、B5 / B6 / B7 为本版新增的分析决策型子场景：A4 与 B5 负责「看全局」，A5 / A6 与 B6 / B7 负责「算深度」。
四、通用技术约束
4.1 时间口径
- 接口中的
start_time/end_time/eta/ata/atb/atd等字段统一为 UTC 秒级时间戳，展示层必须统一转换为北京时间（UTC+8）并明确标注时区。 HistoryWeather使用yyyy-MM-dd HH:mm:ss格式；GetNavWarning使用yyyy-MM-dd HH:mm；潮汐接口使用yyyy-MM-dd。- 轨迹、事件、ETA 三者做时间对齐时，必须先统一到 UTC 再比对，避免 8 小时偏移导致的误判。
4.2 接口边界（超限会报错，不是返回空）
| 接口 | 边界 | 超限处理 |
|---|---|---|
GetShipTrack | 单次 ≤ 1 个月 | 分段循环调用后拼接去重 |
SearchshipApproach | 单次 ≤ 31 天 | 分段循环 |
GetETAShips | start_time ~ end_time ≤ 7 天 | 按周拆分 |
GetPortofCallByPort | 单次 ≤ 7 天 | 30 天内拆连续窗口并去重；更长需开通历史深度 |
GetTideData | 单次 ≤ 90 天 | 按月拆分 |
GetAreaShip | 建议单次 ≤ 1° × 1° | 大范围按网格切分，按 scode / continue 续查 |
GetManyShip | mmsis 上限 100 条 | 分批 |
4.3 调用频率建议
| 接口类型 | 建议频率 | 说明 |
|---|---|---|
位置类（GetSingleShip / GetFleetShip / GetManyShip） | 5–10 分钟 | 推送通道故障时的降级轮询 |
港口清单（GetBerthShips / GetAnchorShips） | 5–10 分钟 | 锚地状态变化慢 |
预抵清单（GetETAShips） | 30 分钟 | 预抵信息滑动刷新 |
区域快照（GetAreaShip） | 15 分钟 | 与区域事件推送交叉对账 |
周边船舶（GetSurRoundingShip） | 5 分钟 | 近程防御主频 |
实况气象（CurrentWeather） | 逐小时 | 数值预报本身 6 小时更新一次 |
预报气象（FutureWeather） | 6 小时 | 与模式更新同步 |
台风（GetAllTyphoon / GetSingleTyphoon） | 6 小时或事件驱动 | 中央气象台发布时点 |
航行警告（GetNavWarning） | 每日 1 次 + 事件驱动 | 频繁变更需商务开通推送 |
潮汐（GetTideData） | 一次性拉 30 天缓存 | 天文潮，稳定 |
历史轨迹（GetShipTrack） | 按需 | 回放 / 取证 / 统计 |
静态档案（SearchPort / SearchShipParticular / GetShipRegistry / GetTides） | 长期缓存（7–30 天） | 几乎不变 |
4.4 降级与容错策略
AIS 数据天然存在上报间隔与信号遮蔽（港内、恶劣天气、设备关闭），业务逻辑必须容忍短时缺失：
- 位置丢失：不要靠轮询判活，改用 AIS 信号消失事件推送 9.7；恢复事件（event_type=2）自动闭环。
- 推送通道故障：所有推送必须有对账任务（快照接口周期比对），超过 N 个周期未收到推送即告警并降级为轮询。
- 格点数据缺测：气象格点缺测时用最近一次有效值填充，并在 UI 上标注「数据缺失」。
- 轨迹漂点：计算前统一做漂点剔除（相邻点推算速度 > 60 节视为异常）。
- AIS 与 PRED 混用：
GetShipTrack的data_source字段区分AIS（真实上报）与PRED（预测补点），做统计分析时必须分离或标注，避免把预测点当实测点。 - 超时与重试：网络类瞬时错误最多重试 1 次；权限类错误（
service_not_enabled/region_out_of_scope/quota_exhausted）禁止原参数重复调用，应转商务流程。
4.5 数据边界与合规
- 来自船讯网：全部船舶动态、港口作业、航次行为、航线、气象、台风、潮汐、航行警告、推送事件。
- 来自客户内部系统：货主与合同、货量与货种、准入船东白名单、设施台账与白名单、执法流程、值班与处置人员、结算与费率规则。
- 关联主键：物流场景为「内部航次号 Voyage ID ↔
mmsi+ 时间窗」；设施场景为「设施台账 ID ↔area_id/ 虚拟参照船mmsi」。 - 实时船位、船队成员、详细轨迹、港口作业数据属于敏感数据，页面需做字段级权限控制，不对外发布原始响应。
4.6 前端呈现统一约定
- 底图统一使用 海图 GIS 平台开发服务 提供的海图瓦片与 JS SDK，保证海图与船舶数据同源。
- 界面基调为明亮 SaaS 风格：浅灰蓝底 + 白色卡片 + 淡蓝主色，禁止暗黑大屏；红色仅用于闯入 / 警戒级事件，橙黄用于预警，正常态一律淡蓝或中性色。
- 大屏页面按 1920×1080 设计并按视口等比缩放，工作台页面按 1440 基准自适应。
- 数值与英文使用等宽字体对齐，中文使用无衬线字体。
4.7 商务开通清单
以下能力需在控制台之外联系船讯网商务开通：GetAreaShip 区域权限、全部推送类服务（9.1–9.8）、CurrentWeather / FutureWeather 全球气象、HistoryWeather 历史气象、超过 1 个月的 GetShipTrack 历史深度、自定义推送频率（高于 10 分钟一包）。