区域船二进制解析说明

适用接口：GET https://api.shipxy.com/apicall/v3/GetAreaShip（区域船舶查询，output=0 即二进制 Base64 编码返回）
请求参数依据：船讯网官方在线文档《1.4 区域船舶查询》(https://apidocs.shipxy.com/475744022e0)
二进制结构依据：《船讯网 API 开发文档 V2》表 11「区域船舶返回结果-二进制」、表 58「8.2 详细数据」、附录 2 / 3 / 5
目标读者：需要对接二进制返回格式、将其反序列化为标准 AIS 船舶数据的后端研发人员

1. 接口概述

1.1 接口功能

区域船舶查询按照区域范围，一次请求该区域内的所有船舶 AIS 数据。可以传多个经纬度坐标点绘制任意多边形查询区域。单次请求的区域建议在 1°×1° 范围以内，这样单次请求即可全部返回数据；范围更大时可自行将区域切分成小区域请求，或使用 scode 分页获取剩余船舶（见 §1.4）。

服务规则与限制：

2 小时未上报数据的船舶不返回——此时无法判定船舶是否还在区域内；

JSON 格式单次约可返回 2600 条船，二进制格式单次约可返回 8000 条船；

使用本服务前需在船讯网控制台创建应用的 key 并联系商务开通权限；购买服务后会设定总的区域查询范围，每次请求的经纬度坐标都不能超出该范围，超出后无法返回数据；

如需更大范围或更高频率的数据，船讯网支持定制 TCP/IP、Kafka 等推送方式接入，可设定区域范围、船舶类型/长度/固定船队列表等筛选方式及推送频率，定制开通请联系商务。

1.2 请求地址与请求参数

请求地址：GET https://api.shipxy.com/apicall/v3/GetAreaShip

参数	类型	必填	说明
`key`	string	必需	船讯网授权码，验证服务权限。需在控制台创建并开通权限；官方文档示例中的 key 已绑定域名，直接使用会返回 status 14（来源域错误），请使用自己的 key
`region`	string	必需	查询区域，经纬度逗号分隔、多个点减号分隔，格式 `lng,lat-lng,lat-lng,lat`。规则：① 多个坐标点必须按顺时针或逆时针依次输入；② 坐标点必须超过 2 个（2 个点只能连一条线，无法划分区域）；③ 必须按先经度后纬度顺序输入；④ 区域不可超出分配的权限范围；⑤ 权限范围内可根据场景自行拆分多个小区域分别请求
`data_type`	integer	可选	数据返回类型：0 仅船舶；1 仅航标；2 仅网位仪；3 船舶+航标；4 船舶+网位仪；5 船舶+航标+网位仪。默认 0
`output`	integer	可选	输出数据格式：0 为二进制 Base64 编码，1 为 JSON 格式，默认 1。注意：当返回数据带有航标或网位仪时（data_type ≠ 0），output 只能是 JSON
`scode`	integer	可选	查询某一区域的会话令牌。区域较大、数据过多无法单次返回时，使用首次请求返回的 scode 再次请求剩余数据，详见 §1.4

请求调用示例：

https://api.shipxy.com/apicall/v3/GetAreaShip?key=<你的key>&region=121.289063,35.424868-122.783203,35.281501-122.167969,33.979809&output=0

1.3 返回格式选择（output 参数）

output	格式	说明
0	二进制 Base64	紧凑、单次可容纳约 8000 艘船，需按本文档反序列化；仅支持纯船舶数据（data_type=0）
1（默认）	JSON	字段名可直接读，单次约 2600 艘，字段语义与二进制完全一致；含航标/网位仪时只能选此格式

两种格式承载同一套逻辑字段（8.2 详细数据表定义），二进制格式只是去掉了字段名、按固定规则紧凑打包。研发联调阶段建议先抓一份 output=1 的 JSON 响应与二进制解析结果比对核验。

1.4 大数据量分页（scode 与 continue）

HTTP 请求单次返回的数据最大为 2666 条船；超出部分需使用首次查询时返回的 scode 再次发起请求；

使用 scode 翻页时查询区域不可变动，否则会生成一个新的查询记录；

关注返回结果中的 continue 字段：为 0 时代表区域内全部船舶数据已经查完，无需再请求；为 1 时代表还有剩余数据，填入 scode 继续请求；

二进制格式下，scode 在公共头第 15–18 字节返回（见 §3），count 为本次返回的船舶条数。

1.5 二进制记录版本说明

二进制记录存在 v=2 / v=4 两个版本：v=4 在 v=2 基础上额外返回 cnname（中文船名）与 newtype（新船舶类型，附录 5）两个字段，记录中相应多出 newtype 定长字段与 cnname 变长字符串。本文档的记录布局按 v=4 描述（样例数据即 v=4 格式）；对接 v=2 时按 §4.3 的说明裁剪即可。

2. 响应整体结构

外层 HTTP 响应体是 JSON，data 字段为 Base64 字符串，解码后才是真正的二进制负载：

HTTP Response Body (application/json)
└── { "status": 0, "msg": "", "data": "<Base64>" }
        └── base64 decode
            └── Binary Payload
                ├── 公共头 23 字节
                └── 船舶记录 × count（变长，紧密排列，无分隔符）

status：数据返回状态，0 表示成功，其他值见官方附录 1；

msg：状态描述；

data：Base64 编码的二进制负载。

样例数据规模：二进制 27 759 字节，公共头声明船舶数 271，实测逐条解析 271/271 条全部成功、结束偏移与总长精确吻合。

3. 公共头（23 字节）

依据官方表 11，Base64 解码后的前 23 字节为公共头：

偏移	字节	类型	字段	说明
0	4	u32 LE	`dataLength`	数据包长度（样例 27753 = 总长 27759 − 6）
4	2	u16 LE	`dataType`	数据包类型（样例 0）
6	1	u8	保留字节	样本中恒为 0x00
7	8	i64 LE	`serviceTime`	服务器当前时间，unix 秒（样例 1789441918 = 2026-09-15 11:11:58 北京时间）
15	4	u32 LE	`scode`	会话令牌，客户端需保存并在下次请求时回传
19	4	u32 LE	`count`	船舶数量（样例 271）

官方表 11 依次列出 dataLength、dataType、serviceTime、scode、船舶数五个字段；实测样本在 dataType 与 serviceTime 之间存在 1 个保留字节，即记录区从偏移 23 开始。解析时建议做双重校验：count 与实际解出的记录数一致，且最后一条记录的结束偏移等于 len(buf)。

4. 船舶记录结构（stShipDetail）

记录区紧跟公共头，每条记录对应一艘船，变长（样例 72–132 字节，平均约 102 字节），依次紧密排列，无长度前缀、无分隔符——记录长度由内部变长字段自然累加得出，这也是二进制格式紧凑的原因。字段顺序与官方表 58 一致：

4.1 记录布局总览

┌─────────────── 定长段 24 字节 ───────────────┬────── 变长字符串段 ──────┬─ 尺寸 ─┬─ dest ─┬─ eta ─┬─ 动态尾段 26 字节 ─┐
│ ShipID u64 │ From u32 │ MMSI u32 │ shiptype │ newtype │ imo u32 │ name │ cnname │ callsign │ L/W/LF/TR/DR │ dest │ eta[4] │ navistat…lasttime │
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

4.2 字段明细表

#	偏移	类型	字段	官方定义（表 58）	样例值
①	0	u64	ShipID	船舶 ID（与 MMSI 相同）	412302277
②	8	u32	From	数据来源：0 岸基 AIS，1 卫星 AIS	0
③	12	u32	MMSI	船舶 MMSI，9 位数字	412302277
④	16	u16	shiptype	船舶类型，见附录 2	30（捕捞）
⑤	18	u16	newtype	新船舶类型（v=4 返回），见附录 5	12（渔船）
⑥	20	u32	imo	IMO 号，7 位；0 = 未提供，2147483647 = 无效值	0
⑦	24	u16 len + UTF-8	name	船舶名称	SUGANYUYUN02277
⑧	变长	u16 len + UTF-8	cnname	中文船名（v=4 返回，部分船舶为空）	苏赣渔运02277
⑨	变长	u16 len + UTF-8	callsign	船舶呼号，4–5 位数字或字母，中国籍船舶以 B 开头	02277
⑩	变长	5 × u16	length / width / left / trail / draught	船长、船宽、左舷距、尾距（分米）；吃水（毫米）	380 / 80 / 40 / 120 / 0
⑪	变长	u16 len + UTF-8	dest	目的地（AIS 设备原始输入，可能为空或无意义内容）	"0"
⑫	变长	4 × u8	eta	预到时间，[MM][DD][HH][MM] 逐字节存放	`01 01 01 01`
⑬	变长	u16	navistat	航行状态，见附录 3；255 = 无数据	255
⑭	+2	i32	lat	纬度，1/1000000 度，[-90000000, 90000000]	34400077
⑮	+6	i32	lon	经度，1/1000000 度，[-180000000, 180000000]	121917450
⑯	+10	u16	hdg	船首向，1/100 度，[0, 35900]；超上限即无数据	51100（无数据）
⑰	+12	u16	cog	航迹向，1/100 度，[0, 35990]；超上限即无数据	16580
⑱	+14	u16	sog	对地航速，毫米/秒，[0, 52576]（即 0–52.576 m/s，约 0–102 节）	977
⑲	+16	i16	rot	转向率，1/100 度/秒，[-1200, 1200]，顺时针为正；32767 = 无数据	0
⑳	+18	i64	lasttime	数据更新时间，unix 时间戳（秒）	1789440605

偏移量：①–⑥ 为记录内绝对偏移（0–23）；⑦–⑫ 变长顺次累加；⑬–⑳ 为动态尾段内相对偏移，尾段共 26 字节固定长度。

4.3 对接 v=2 版本的裁剪

v=2 记录相比 v=4：无 newtype（⑤，2 字节）、无 cnname（⑧变长串）。对接 v=2 时删去这两项即可，其余完全一致。判断依据：下发二进制数据时服务端使用的记录版本。

4.4 关键编码规则

字节序：所有多字节整数均为小端序（little-endian）。

字符串：UTF-8 编码，无 NUL 终止符，前置 u16 长度前缀（字节数，非字符数）。

定点数：全程不使用 IEEE-754 浮点，坐标 /1e6、角度 /100、sog /1000（米/秒）、rot /100、尺寸 /10（米）、吃水 /1000（米）。

有符号性：lat、lon、rot、lasttime、serviceTime 为有符号整数，其余为无符号。跨南北纬、东西经区域 lat/lon 出现负值，务必按有符号解析。

时间：lasttime / serviceTime 为 unix 秒时间戳，转北京时间 +8 小时。

4.5 无数据标识与处理约定

部分 AIS 船载设备未上报某些字段，二进制中按官方约定的标识值填充。建议统一转换为 null（Python None），避免输出负数之类的非物理值：

字段	标识值	出现原因	处理建议
hdg / cog	> 35900 / > 35990（常见 51100）	AIS 缺省航向 511°（ITU-R M.1371 规定）	输出 null
rot	32767	设备未上报转向率	输出 null
navistat	255	设备未上报航行状态	输出 null
imo	0 或 2147483647	未提供 / 无效值	输出 null
eta	全 0、`01-01 00:00`、`01-01 01:01`，或月/日/时/分超出合法范围	AIS 设备未设置 ETA 时的缺省填充	输出 null
draught / length 等	0	设备未上报	按实际值 0 输出或上层判空

样例统计（271 条）：hdg 无数据 190 条、rot 无数据 108 条、navistat 无数据 227 条、eta 未设置 221 条——渔船及小型船设备上报不全属于常态，业务侧必须按「字段可能缺失」设计。

5. 完整解析代码（Python 3.10+）

枚举字典 SHIPTYPE_NAMES / NEWTTYPE_NAMES / NAVISTAT_NAMES 的完整内容见附录 A/B/C；含命令行入口的完整可运行代码见 §9 附录。

6. 解析结果样例（真实样本节选）

输入样例：27 759 字节二进制、271 条记录（2026-09-15 连云港附近海域）。

6.1 记录样例 1（渔船，v=4 含中文船名）

{
  "mmsi": 412302277,
  "data_source": 0,
  "shiptype": 30,
  "shiptype_name": "捕捞",
  "newtype": 12,
  "newtype_name": "渔船",
  "imo": null,
  "name": "SUGANYUYUN02277",
  "cnname": "苏赣渔运02277",
  "callsign": "02277",
  "length_m": 38.0,
  "width_m": 8.0,
  "left_m": 4.0,
  "trail_m": 12.0,
  "draught_m": 0.0,
  "dest": "0",
  "eta": null,
  "navistat": null,
  "navistat_name": "未知",
  "lat": 34.400077,
  "lon": 121.91745,
  "hdg": null,
  "cog": 165.8,
  "sog_ms": 0.977,
  "sog_kn": 1.9,
  "rot": 0.0,
  "last_time_utc": 1789440605,
  "last_time": "2026-09-15 10:50:05"
}

典型渔船记录：imo / eta / navistat / hdg 未上报（null），位置与航速正常。

6.2 记录样例 2（集装箱船，全字段上报）

{
  "mmsi": 477832300,
  "data_source": 0,
  "shiptype": 100,
  "shiptype_name": "集装箱",
  "newtype": 3,
  "newtype_name": "集装箱船",
  "imo": 9484390,
  "name": "COSCO VALENCIA",
  "cnname": "",
  "callsign": "VRLY7",
  "length_m": 261.0,
  "width_m": 32.0,
  "left_m": 10.0,
  "trail_m": 68.0,
  "draught_m": 10.3,
  "dest": "CN ZOS",
  "eta": "09-16 09:00",
  "navistat": 0,
  "navistat_name": "在航(主机推动)",
  "lat": 34.935742,
  "lon": 121.640362,
  "hdg": 206.0,
  "cog": 134.9,
  "sog_ms": 0.514,
  "sog_kn": 1.0,
  "rot": 0.01,
  "last_time_utc": 1789440881,
  "last_time": "2026-09-15 10:54:41"
}

商船全字段上报：IMO、ETA（次日 09:00）、航行状态（在航）齐全；hdg=206.0° 与 cog=134.9° 差异大是该船正在转向/掉头（rot=0.01°/s），属正常现象。

7. 对接注意事项

首条记录从偏移 23 开始：dataType 之后有 1 个保留字节，直接从偏移 7 读 serviceTime 会错位。正确做法：serviceTime @7、scode @15、count @19、记录区 @23。

记录无分隔符，靠链式推进：从偏移 23 起按字段表逐条解析，上一条的结束位置即下一条的开始位置；解析完 count 条后校验结束偏移是否等于总长，不等说明结构理解有误（此时应优先检查是否漏/多读了 v=4 的 newtype 或 cnname）。

不要用模式匹配扫 MMSI 定边界：MMSI 是 9 位数字但渔船 MMSI 前缀多样（102/412/413…），字符串内容也可能恰好构成合法 MMSI，模式扫描存在漏检与误检风险；链式解析天然无此问题。

无数据字段输出 null，不要输出 -1 或原样标识值：船速、航向等物理量非负，输出负数会污染下游统计；统一转 null 后由业务侧判空。

eta 缺省识别：00-00 00:00、01-01 00:00、01-01 01:01 以及非法日期（如 11-31）均为设备未设置，应输出 null，不要当真实到港时间入库。

dest 为设备自由输入文本：样例中大量出现 "0"、"11"、"13 B#" 等无意义内容，不能直接当港口名；需要标准港口时应使用 JSON 格式（output=1）返回的 dest_std / destcode（由船讯网港口库标准化），二进制格式不含这两个字段。

大区域记得用 scode 翻页：单次请求最多返回 2666 条船，超出后把本次返回的 scode（二进制在公共头 @15）填入下次请求继续拉取剩余船舶；翻页期间 region 必须保持原样，直到 continue=0 表示区域内全部查完。

lasttime 与 2 小时规则：官方规则为 2 小时未上报的船不返回，lasttime 可作为数据新鲜度依据；样例 lasttime 最老 24 小时内（卫星通道数据时间跨度更长）。

字符串长度前缀是 u16：单字段理论最长 65535 字节，实际船名/目的地远短于此；解析时仍建议对异常长度（如 > 256）做防御性校验。

10.

样本分布特征：渔船占多数时 hdg/navistat/eta 的无数据比例很高（本样例约 70–80%），属于船载设备上报能力差异，不代表接口异常。

8. 附录

附录 A：船舶类型（shiptype，附录 2 摘录）

编号	类型	编号	类型
20–29	地效应船	50	引航船
30	捕捞	51	搜救船
31	拖引	52	拖轮
32	拖引且船长>200m或船宽>25m	53	港口供应船
33	疏浚或水下作业	54	载有防污染装置和设备的船舶
34	潜水作业	55	执法艇
35	参与军事行动	56–57	备用（当地任务分配）
36	帆船航行	58	医疗船
37	娱乐船	59	符合 18 号决议(Mob-83)的船舶
40–49	高速船	60–69	客船
70–79	货船	80–89	油轮
90–99	其他类型的船舶	100	集装箱

附录 B：新船舶类型（newtype，附录 5 摘录）

编号	类型	编号	类型
1	散货船	8	滚装船
2	杂货船	9	其它货船（shiptype 70–79）
3	集装箱船（对应 shiptype=100）	10	其它油船（shiptype 80–89）
4	油船	11	客船（shiptype 60–69）
5	化学品船	12	渔船（shiptype=30）
6	LNG	13	拖轮/引航船（shiptype 50/52）
7	LPG	99	其它

附录 C：航行状态（navistat，附录 3 摘录）

编号	状态	编号	状态
0	在航（主机推动）	8	靠帆船提供动力
1	锚泊	9	保留（HSC 航行状态修正）
2	失控	10	保留（WIG 航行状态修正）
3	操纵受限	11–14	保留（将来使用）
4	吃水受限	15	未定义，缺省
5	靠泊	255	无数据（非官方枚举，实测样本出现）
6	搁浅
7	捕捞作业

附录 D：单位换算速查

原始字段	原始单位	换算	常用单位
lat / lon	1/1000000 度	÷ 1e6	度（WGS84）
hdg / cog	1/100 度	÷ 100	度
sog	毫米/秒	÷ 1000（× 1.943844）	米/秒（节）
rot	1/100 度/秒	÷ 100	度/秒
length / width / left / trail	分米	÷ 10	米
draught	毫米	÷ 1000	米
lasttime / serviceTime	unix 秒	+8h（北京时）	日期时间

9. 附录：完整解析器代码（shipxy_binary_parser.py）

以下为完整可运行版本（含枚举字典与命令行入口），可直接复制保存为 shipxy_binary_parser.py 使用，271/271 条样例实测通过：

说明：为与文档对外发布版本保持一致，命令行入口仅保留基础演示输出（公共头 + 3 条记录样例）；统计验证逻辑可在此基础上按需扩展。

本文档请求参数依据船讯网官方在线文档《1.4 区域船舶查询》(https://apidocs.shipxy.com/475744022e0)。

区域船二进制解析说明

1. 接口概述#

1.1 接口功能#

1.2 请求地址与请求参数#

1.3 返回格式选择（output 参数）#

1.4 大数据量分页（scode 与 continue）#

1.5 二进制记录版本说明#

2. 响应整体结构#

3. 公共头（23 字节）#

4. 船舶记录结构（stShipDetail）#

4.1 记录布局总览#

4.2 字段明细表#

4.3 对接 v=2 版本的裁剪#

4.4 关键编码规则#

4.5 无数据标识与处理约定#

5. 完整解析代码（Python 3.10+）#

6. 解析结果样例（真实样本节选）#

6.1 记录样例 1（渔船，v=4 含中文船名）#

6.2 记录样例 2（集装箱船，全字段上报）#

7. 对接注意事项#

8. 附录#

附录 A：船舶类型（shiptype，附录 2 摘录）#

附录 B：新船舶类型（newtype，附录 5 摘录）#

附录 C：航行状态（navistat，附录 3 摘录）#

附录 D：单位换算速查#

9. 附录：完整解析器代码（shipxy_binary_parser.py）#