位置验真 API

根据上报的 Wi-Fi、基站与 GNSS 三类证据，验证上报位置是否可信，返回风险等级与可解释的证据摘要。

1. 接口基本信息

  • 接口名称：位置验真
  • 接口地址：https://positionboard.newayz.com/locationtruth/v1/verify-location
  • 请求方法：POST
  • 请求格式：application/json
  • 接口描述：根据上报的 Wi-Fi、基站与 GNSS 三类证据，验证上报位置是否可信，返回风险等级与可解释的证据摘要。
  • 鉴权方式：请求头 X-API-Key 必填，缺失或非法返回 401；也兼容 Authorization: ApiKey <key>。

2. 请求参数

参数名 类型 必填 描述
request_id string 是 请求唯一标识，用于关联日志与防重放
scene_code string 是 业务场景编码，如 FIELD_CHECKIN / STORE_REDEEM
gnss object 否 GNSS 定位结果（WGS84），不上报则只做 Wi-Fi 与 Cell 比对
gnss.latitude number 条件必填 WGS84 纬度，-90 ~ 90
gnss.longitude number 条件必填 WGS84 经度，-180 ~ 180
gnss.accuracy number 条件必填 水平精度（米），≥ 0；大于 500 视为不可用
gnss.timestamp integer 否 定位时间戳（毫秒）
wifis array 是 Wi-Fi 观测列表，必须非空
wifis[].macAddress string 是 AP 的 MAC 地址，如 32:03:be:44:51:22
wifis[].signalStrength number 否 信号强度（dBm），负值
wifis[].frequency number 否 频点（MHz），如 2412
cellulars array 是 基站观测列表，必须非空
cellulars[].cellId integer 是 小区 ID
cellulars[].mobileCountryCode integer 是 移动国家码（MCC），如 460
cellulars[].mobileNetworkCode integer 是 移动网络码（MNC）
cellulars[].locationAreaCode integer 是 位置区域码（LAC）
cellulars[].signalStrength number 否 信号强度

说明：gnss 传入时其三个字段必填；不传 gnss 时不影响请求成功。

3. 响应参数

参数名 类型 描述
request_id string 原样回传请求中的 request_id
risk_level enum LOW / MEDIUM / HIGH / UNKNOWN 风险等级
reason_codes array 命中的原因码，见下表
evidence_summary object 可解释的证据摘要
evidence_summary.gnss_available boolean 是否上报了 GNSS
evidence_summary.gnss_valid boolean GNSS 精度是否可用于一致性比对
evidence_summary.gnss_gcj02 object / null 转换后的 GNSS 坐标 { lat, lng }（GCJ02）
evidence_summary.wifi_location object / null Wi-Fi 分源定位结果（GCJ02）
evidence_summary.cell_location object / null Cell 分源定位结果（GCJ02）
evidence_summary.dist_gnss_wifi_m number / null GNSS 与 Wi-Fi 定位的距离（米）
evidence_summary.dist_gnss_cell_m number / null GNSS 与 Cell 定位的距离（米）
evidence_summary.dist_wifi_cell_m number / null Wi-Fi 与 Cell 定位的距离（米）
evidence_summary.gnss_accuracy_m number / null 上报的 GNSS 原始精度（米）
policy_result enum ALLOW / REVIEW / REJECT 策略动作

响应示例：

{
  "request_id": "req-20261104-0001",
  "risk_level": "HIGH",
  "reason_codes": ["GPS_WIFI_CELL_MISMATCH"],
  "evidence_summary": {
    "gnss_available": true,
    "gnss_valid": true,
    "gnss_gcj02": { "lat": 43.781484239177914, "lng": 87.60269192936393 },
    "wifi_location": null,
    "cell_location": { "lat": 29.059109, "lng": 106.638424 },
    "dist_gnss_wifi_m": null,
    "dist_gnss_cell_m": 2351453.4,
    "dist_wifi_cell_m": null,
    "gnss_accuracy_m": 20
  },
  "policy_result": "REVIEW"
}

4. 错误处理

HTTP code 说明
400 INVALID_REQUEST 参数缺失或格式错误，如 wifis 为空、纬度超出范围；此时不返回 risk_level
401 UNAUTHORIZED 缺少 X-API-Key，或该 Key 不在服务端允许列表中
404 NOT_FOUND 路由不存在
500 INTERNAL_ERROR 服务端内部错误

错误响应体统一为：

{
  "error": "INVALID_REQUEST",
  "message": "cellulars is required and must be non-empty"
}

5. 请求示例

URL

https://positionboard.newayz.com/locationtruth/v1/verify-location

请求方式

curl -X POST "https://positionboard.newayz.com/locationtruth/v1/verify-location" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "req-20261104-0001",
    "scene_code": "FIELD_CHECKIN",
    "gnss": {
      "latitude": 43.78026144,
      "longitude": 87.59985397,
      "accuracy": 20,
      "timestamp": 1793272340935
    },
    "wifis": [
      { "macAddress": "32:03:be:44:51:22", "signalStrength": -48, "frequency": 2412 }
    ],
    "cellulars": [
      {
        "cellId": 10437,
        "signalStrength": 30,
        "mobileCountryCode": 460,
        "mobileNetworkCode": 1,
        "locationAreaCode": 6325
      }
    ]
  }'

6. 常见原因码

reason_codes 说明
GPS_WIFI_CELL_MISMATCH GNSS 坐标与 Wi-Fi / Cell 定位不一致
WIFI_CELL_MISMATCH 无 GNSS 基准时，Wi-Fi 与 Cell 定位相互不一致
LOW_GNSS_ACCURACY GNSS 精度大于 500 米，不参与比对
LOW_EVIDENCE 可用证据不足，无法判定

7. 注意事项

  • API Key：请求头 X-API-Key 必填；未通过鉴权时返回 401，且不返回任何验真结论。
  • 幂等与防重放：request_id 必须唯一且可追溯到调用方业务单据，服务端据此关联日志。
  • 坐标系：请求中的 gnss 使用 WGS84；响应 evidence_summary 内的所有坐标均为 GCJ02，可直接用于地图展示。
  • GNSS 精度：accuracy 大于 500 米时视为不可用，本次请求降级为 Wi-Fi 与 Cell 之间的比对，并附带 LOW_GNSS_ACCURACY 原因码。
  • 结论含义：risk_level 是基于当前证据的一致性结论，不等同于作弊判定；UNKNOWN 表示证据不足，建议转人工复核。