track-vessel-traffic

当用户询问某个区域的实时航运活动时（船舶位置、黑暗船队/中断候选船只或油轮动态）使用此技能。返回一个边界框的时间点 AIS 快照。

身份验证

服务器到服务器的调用方（代理、脚本、SDK）必须通过 X-WorldMonitor-Key 头部提供 API 密钥。Authorization: Bearer … 用于 MCP/OAuth 或 Clerk JWT——不适用于原始 API 密钥。

X-WorldMonitor-Key: wm_0123456789abcdef0123456789abcdef01234567

在 https://www.worldmonitor.app/pro 申请密钥。

端点

GET https://api.worldmonitor.app/api/maritime/v1/get-vessel-snapshot

参数

名称	位置	是否必需	格式	备注
ne_lat、ne_lon、sw_lat、sw_lon	query	否	边界框（十进制度数）	限定到特定区域——推荐使用；全球范围的快照数据量很大。
include_candidates	query	否	boolean	是否包含中断/异常活动候选船只。
include_tankers	query	否	boolean	是否包含油轮叠加层。
jmespath	query	否	JMESPath，长度 ≤ 1024 字符	服务端投影。

响应结构

{
  "snapshot": { "vessels": ["…"], "…": "…" },
  "fetchedAt": 1783250000000,
  "dataAvailable": true
}

降级契约： 当 snapshot 为空或缺失，且 fetchedAt: 0 或 dataAvailable: false 时，表示 AIS 数据源不可用——是"无数据"，而绝非"无船只"。AIS 覆盖范围同样不包括已关闭应答器的船舶；轨迹缺失并不等同于船舶不存在。

示例

霍尔木兹海峡边界框（含油轮）：

curl -s --get -H "X-WorldMonitor-Key: $WM_API_KEY" \
  'https://api.worldmonitor.app/api/maritime/v1/get-vessel-snapshot' \
  --d…