概览

所有接口均以 /api 为前缀，请求与响应一律 application/json; charset=utf-8。 除瓦片与静态地图返回二进制图片外，其余接口都遵循统一的响应信封： 

{
  "ok": true,
  ...                      // 各接口自己的字段
}

// 失败时
{ "ok": false, "error": "人类可读的错误描述" }
跨域：/api、/vendor、/shared、/sdk 四个前缀均已开放 CORS，可以直接在浏览器里跨域调用。

接口一览

方法路径说明
GET/api/health服务健康检查与运行指标
GET/api/coord/convert两个坐标系之间互转
GET/api/coord/all一次返回全部坐标系的表示
GET/api/geocode/search关键词 / 周边 / 多边形搜索
GET/api/geocode/reverse逆地理编码（坐标→地址）
GET/api/geocode/suggest输入联想（只回名称与坐标）
GET/api/tiles/sources可用瓦片源列表
GET/api/tiles/{id}/{z}/{x}/{y}.png取瓦片（透传代理 + 本地缓存）
GET/api/staticmap服务端渲染静态地图 PNG
GET/api/route路线规划（驾车 / 骑行 / 步行）
GET/api/markers标注的增删查
GET/api/merchants/list已通过审核的认证商户

鉴权与配额

接口默认匿名可用（部署者可在后台把 KEY_REQUIRED 打开强制校验）。 带上 Key 后，服务端会按 Key 统计用量并执行每日配额。

三种携带方式任选其一，服务端都认：

?key=YOUR_KEY                      // 查询参数（瓦片是 <img>，只能走这种）
X-API-Key: YOUR_KEY                // 请求头
Authorization: Bearer YOUR_KEY
瓦片是 <img> 标签加载的，带不了请求头 —— 所以 Key 一律以查询参数传递。 如果你的接口能调通但底图 401，检查瓦片 URL 上有没有带 key。

Scope

创建 Key 时按最小权限勾选，服务端会校验调用的接口是否落在授权范围内：

scope覆盖接口
coord/api/coord/*
geocode/api/geocode/*
tiles/api/tiles/*
staticmap/api/staticmap
route/api/route
stats统计类接口

坐标系约定

服务端内部一律使用 WGS84。对外返回的坐标默认也是 WGS84， 需要其它坐标系时传 crs 参数，由服务端换算。

不要在客户端先转一次、再让服务端转一次 —— 会产生双重偏移。 把原始坐标系通过 crs 告诉服务端，转换只发生一次。
标识说明典型来源
WGS84GPS 原始坐标设备定位、OSM 数据
GCJ02火星坐标（加密偏移）高德、腾讯
BD09百度坐标（在 GCJ02 上二次加密）百度地图
CGCS2000国家大地坐标系测绘成果
EPSG:3857Web 墨卡托投影（单位：米）Web 地图渲染
试一试：坐标系互转

错误格式

{ "ok": false, "error": "缺少 lng / lat 参数" }

HTTP 状态码与语义一致：400 参数问题、401/403 鉴权问题、429 限流、500 服务端异常。业务上以 ok 字段为准。

坐标转换

GET /api/coord/convert scope: coord
参数必填说明
lng是经度
lat是纬度
from是源坐标系
to是目标坐标系
GET /api/coord/convert?lng=116.39124&lat=39.90749&from=WGS84&to=GCJ02

{
  "ok": true,
  "from": "WGS84",
  "to": "GCJ02",
  "input": { "lng": 116.39124, "lat": 39.90749 },
  "output": { "lng": 116.397428, "lat": 39.908838 }
}
GET /api/coord/all scope: coord

一次返回所有坐标系下的表示，并附带与 WGS84 的偏移量（米），便于直观对照。

GET /api/coord/all?lng=116.39124&lat=39.90749&from=WGS84

{ "ok": true, "crs": ["WGS84","GCJ02","BD09",...], "data": {...}, "offsets": { "GCJ02": 559, "BD09": 622 } }

地理编码

GET /api/geocode/search scope: geocode
参数说明
q关键词，如「天安门」
limit返回条数，默认 10
crs输入坐标系，默认 WGS84
center周边搜索中心，格式 lng,lat
radius周边半径（米），配合 center 使用
polygon多边形范围，lng,lat;lng,lat;… 分号分隔（不是 JSON）
bbox矩形范围。服务端不换算，需自己转成 WGS84
modeauto / remote / local

center 与 polygon 会由服务端按 crs 换算； bbox 直接喂给空间索引不换算 —— 这是刻意的不一致， 因为 bbox 通常来自地图视口，已经是 WGS84。

GET /api/geocode/reverse scope: geocode

参数 lng / lat / crs / mode。在线失败会降级到本地 POI 库：按 300m → 1km → 3.4km → 11km 逐级放大找最近的地标。

降级结果带 "source": "local-reverse" 与 "degraded": true，地址由「省 市 区 名称」拼成（离线库没有门牌号）。

mode=local 会跳过上游、只用离线库，响应稳定在毫秒级。 上游不可达时远程要等满超时才降级（实测 8 秒）， 而「给标注起个名字」这类用途用本地 93 万条 POI 完全够 —— 前端加标注走的就是这条。
GET /api/geocode/suggest

输入联想，只回 name / city / category / lng / lat，响应体小，适合边输入边查。

瓦片

GET /api/tiles/sources scope: tiles 
{
  "ok": true,
  "sources": [{
    "id": "osm",
    "name": "OpenStreetMap 标准",
    "maxZoom": 19,
    "attribution": "© OpenStreetMap contributors",
    "kind": "raster",
    "proxyUrl": "/api/tiles/osm/{z}/{x}/{y}.png"
  }]
}
GET /api/tiles/{sourceId}/{z}/{x}/{y}.png

取瓦片。服务端先查本地磁盘缓存，未命中再回源，失败时渲染兜底瓦片（不会返回 404 空白图）。响应头 X-Tile-Cache 标识命中情况：HIT / MISS / FALLBACK。

静态地图

GET /api/staticmap scope: staticmap
参数说明
centerlng,lat，地图中心
zoom缩放级别
size尺寸，如 640x360
markers标注，lng,lat,label 多个用 | 分隔
path折线，lng,lat;lng,lat;…
crs输入坐标系，默认 WGS84
GET /api/staticmap?center=116.397,39.909&zoom=12&size=640x360&markers=116.397,39.909,天安门

路线规划

自研离线引擎，基于本地 OSM 路网构建图结构，驾车 / 骑行 / 步行三种出行方式， 不调用任何外部路径服务。

GET /api/route scope: route
参数说明
from起点，lng,lat
to终点，lng,lat
profilecar（驾车）/ bike（骑行）/ foot（步行）
crs输入坐标系，结果按它转回
路网数据缺少路口名称与单行道属性，因此不提供路口级的转向指引， 只保证几何路径与距离/耗时估算正确。需要导航级指引时应接入专门的数据源。

标注

GET /api/markers

列出全部标注。带登录态（站点 Cookie）创建时会自动记上 owner，未登录创建的标注 owner 为空串。

POST /api/markers 
{
  "name": "公司前台",
  "lng": 116.397, "lat": 39.909,
  "crs": "GCJ02",            // 输入坐标系，服务端统一存 WGS84
  "icon": "pin", "color": "#d33a2c",
  "note": "快递放这里"
}

商户认证

商户由商家自主提交，平台只做形式审核。通过后的商户进入独立认证图层与搜索结果， 带「认证」角标。

GET /api/merchants/list 公开

只返回已审核通过的商户。参数 bbox（矩形过滤）、q（名称关键词）、limit（默认 300，上限 2000）。

POST /api/merchants 需登录 
{
  "name": "示例餐厅（望京店）",
  "category": "餐饮",
  "lng": 116.47, "lat": 39.99,
  "address": "北京市朝阳区望京街 1 号",
  "phone": "010-12345678",
  "description": "营业时间 10:00-22:00",
  "images": ["https://…/a.jpg"]     // 最多 6 张
}

提交后状态为 pending；管理员通过后变 approved，驳回为 rejected 并附 review.reason。

状态含义可操作
pending待审核可修改
approved已通过，公开展示可下架
rejected已驳回改后可重新提交
offline商家自行下架改后可重新提交
GET /api/merchants/mine 需登录

我提交的全部商户（含待审与驳回），按 owner 隔离。

PUT /api/merchants/:id 需登录

修改自己的商户，仅 pending / rejected 状态可改。修改后状态回到 pending。

站点账号接口

面向「控制台」的一组接口，用 HttpOnly Cookie（oms_portal）维持会话， 不是给第三方服务端调用的 —— 需要服务端集成请用 API Key。

方法路径说明
POST/api/portal/register注册（成功后直接下发会话）
POST/api/portal/login登录
POST/api/portal/logout退出
GET/api/portal/me当前登录用户
GET/api/portal/keys我的 Key 列表
POST/api/portal/keys创建 Key（明文仅返回一次）
DELETE/api/portal/keys/:id删除 Key
GET/api/portal/usage用量统计（汇总自己全部 Key）
GET/api/portal/markers我的标注
账号体系与管理后台相互独立：门户用户存 data/portal/， 管理员存 data/auth/，会话 Cookie 也不同。门户用户默认没有任何后台权限。

限流与错误码

状态码含义常见原因
400参数错误缺少必填参数、坐标超范围、图片数量超限
401未登录调用需登录接口但没有会话 Cookie
403无权限scope 不匹配、操作别人的资源
404不存在资源 ID 错误，或不属于当前用户
429限流超过 Key 每日配额或每 IP 频率上限
500服务端异常见服务端日志

公开接口另有 IP 白名单 + 每 IP 限流，默认关闭，部署公网后可在后台「访问控制」页开启。