REST 服务

平台的服务接口兼容 ArcGIS REST 风格，任何能发 HTTP 请求的程序都可以直接调用。本页列出常用的地址与参数；用 JavaScript 时也可以直接用 JS SDK，它封装了这些地址。

通用约定

服务地址：https://map-demo.geobridge.cn/geobridge-mapserver/rest/geodata/services/<服务路径>/<能力>/…。服务路径为服务名，服务放在目录中时为 目录/服务名，例如 …/services/demo/city-roads/MapServer。目录与服务名逐段编码，目录分隔的 / 不要编码成 %2F。
API Key：「API Key」级别的服务在地址后加 token=gb_xxx…，或用请求头 X-GeoBridge-Token: gb_xxx…，见 API Key 与来源白名单。下面的示例用查询参数，便于复制到浏览器里试；公开服务去掉 token 即可。
返回格式：元数据、查询类接口用 f 指定格式。f=json 返回 JSON，查询接口另支持 f=geojson；不写 f 时默认返回 HTML 调试页面，程序调用请总是带上 f。
请求方法：读接口同时接受 GET 与 POST 表单（application/x-www-form-urlencoded），参数相同。条件很长时用 POST，但 token 要放在地址的查询参数里或请求头中，表单里的 token 不认。
错误：访问被拒绝时返回 JSON 错误体与 401、403 等状态码，见错误码。服务内部的错误可能以 HTTP 200 返回 {"error": …}，请同时检查响应体。

下文用 $S 代表 https://map-demo.geobridge.cn/geobridge-mapserver/rest/geodata/services/city-roads。

服务目录

列出当前 API Key（或登录用户）能访问的服务：

bash

curl 'https://map-demo.geobridge.cn/geobridge-mapserver/rest/geodata/catalog?f=json&token=gb_xxx…'

json

{
  "services": [
    { "path": "demo/city-roads", "name": "city-roads", "folder": "demo", "title": "道路",
      "types": ["MapServer", "FeatureServer", "VectorTileServer"], "accessLevel": "KEY" }
  ],
  "truncated": false
}

请求方	结果
带有效 Key	该 Key 所属工作空间中「公开」与「API Key」级别的服务
已登录、不带 Key	登录用户有读权限的工作空间中的全部服务
匿名	401 `TOKEN_REQUIRED`（平台不提供匿名列出全部公开服务的接口）
Key 无效、已撤销、已过期或不在白名单内	401 `TOKEN_INVALID`

按路径排序，types 只含已开启的服务能力。accessLevel 为 PUBLIC（公开）、KEY（API Key）或 PRIVATE（私有）。
最多返回 1000 条，超出时截断并返回 "truncated": true，不分页。
已停止的服务也会列出，访问时返回 503。
目录不含服务范围，范围请从服务元数据的 fullExtent 读取。

MapServer（地图服务）

地址	说明
`$S/MapServer?f=json`	服务元数据：图层列表、坐标系、全图范围（`fullExtent`）、切片方案（`tileInfo`，启用了预切片的服务才有）等
`$S/MapServer/layers?f=json`	全部图层的详细信息
`$S/MapServer/<图层编号>?f=json`	单个图层的元数据（字段、几何类型等）
`$S/MapServer/tile/{z}/{y}/{x}`	切片，行号 `{y}` 在前、列号 `{x}` 在后
`$S/MapServer/export`	按范围出图
`$S/MapServer/identify`	点击识别要素
`$S/MapServer/find`	按文本在字段中查找要素
`$S/MapServer/<图层编号>/query`、`$S/MapServer/<图层编号>/<要素 ID>`	要素查询与按 ID 取要素，参数与 FeatureServer 相同
`$S/MapServer/WMTS/1.0.0/WMTSCapabilities.xml`	WMTS 能力文档
`$S/MapServer/WMSServer`、`$S/MapServer/WFSServer`、`$S/MapServer/WCS`、`$S/MapServer/tms`、`$S/ogcapi`	WMS、WFS、WCS、TMS、OGC API，见 OGC 服务概览

切片

bash

curl -o tile.png 'https://map-demo.geobridge.cn/geobridge-mapserver/rest/geodata/services/city-roads/MapServer/tile/12/1552/3372?token=gb_xxx…'

未预切片的服务（控制台发布的矢量与栅格服务默认如此）按需出图：一律返回 256×256 的 PNG，切片网格为 Web 墨卡托（EPSG:3857）的 XYZ 网格，没有数据的位置返回透明 PNG。需要矢量瓦片（PBF）时请用下文的 VectorTileServer。
启用了预切片的服务返回预切的切片，图片格式由服务的切片方案决定（见元数据的 tileInfo），没有数据的位置返回 204（无内容）；这类服务没有切片方案时返回 404，错误码 TILING_NOT_CONFIGURED。
级别、行列号为负数时返回 400。
在 MapLibre、OpenLayers 中配置切片模板时请注意 {y}、{x} 的顺序，写反会请求到错误的位置。

export：按范围出图

参数	说明
`bbox`	出图范围 `xmin,ymin,xmax,ymax`；不给时用服务的初始范围
`bboxSR`	`bbox` 的坐标系（EPSG 编号），默认为服务坐标系
`imageSR`	出图坐标系，默认为服务坐标系
`size`	图片宽高 `宽,高`，默认 `400,400`
`dpi`	默认 96
`format`	`png`（默认）或 `jpg`
`transparent`	`true` 时背景透明，默认 `false`
`layers`	要绘制的图层：`show:0,2`（只画这些）、`hide:1`（默认可见图层中去掉这些）、`include:3`（默认可见图层再加上这些）、`exclude:1`（同 `hide`）；不给时画默认可见的图层
`layerDefs`	按图层追加的属性条件，写成 `图层编号:条件`，如 `0:"类型"='主干道'`；多个图层用逗号分隔，因此条件本身不能含 `,` 与 `:`
`f`	`image` 直接返回图片；`json` 返回包含图片地址（`href`）、范围（`extent`）与比例尺的 JSON；`extent` 的坐标值与其中的 `spatialReference` 都是出图坐标系（`imageSR`，没有给出时为服务坐标系），不是 `bboxSR`

bash

curl -o map.png 'https://map-demo.geobridge.cn/geobridge-mapserver/rest/geodata/services/city-roads/MapServer/export?bbox=116.30,39.85,116.50,40.00&bboxSR=4326&imageSR=3857&size=800,600&format=png&transparent=true&f=image&token=gb_xxx…'

有图层因比例尺或其他原因没有绘制时，响应头 X-GeoBridge-Omitted-Layers 列出这些图层的编号（逗号分隔）。

数据量大的图层在小比例尺下会被自动省略（按整层要素数估算一张图要画的要素过多）。若图层的样式按比例尺分级、并用属性过滤控制小比例尺下画哪些要素（如道路在全市视野只画高速与主干道），平台按当前比例尺下实际生效的规则估算要素数，过滤后足够稀疏就照常绘制；规则中有不带过滤条件的（或 ElseFilter）时仍按整层估算。按此绘制的图层每张图有读取要素数与时长上限，超限时停止读取并在上述响应头中列出。某个比例尺档位首次出图时平台要先统计要素数，统计完成前该图层按整层规则省略，这类结果不进缓存。服务与图层 JSON 中的 minScale 与此一致：分级样式的图层报按实际生效规则还能出图的最小比例尺（能一直出图时为 0），ArcGIS JS 等按 minScale 隐藏图层的客户端因此在小比例尺下仍会请求它。要素数在服务启动或重新加载后由平台在后台统计，统计完成前 minScale 按整层要素数给出（更保守）。

identify：点击识别

参数	说明
`geometry`	点击位置，如 `{"x":116.40,"y":39.91}`
`geometryType`	`esriGeometryPoint`
`sr`	`geometry` 与 `mapExtent` 的坐标系，如 `4326`
`mapExtent`	当前地图视野 `xmin,ymin,xmax,ymax`
`imageDisplay`	地图画面的 `宽,高,dpi`，如 `800,600,96`；与 `mapExtent`、`tolerance` 一起换算容差
`tolerance`	容差像素，默认 0；点要素与细线建议 3 左右
`layers`	`top`（最上层命中的图层）、`visible`（可见图层）或 `all`（全部图层），可加 `:编号` 限定图层，如 `visible:0,1`
`returnGeometry`	是否返回几何，默认 `true`
`f`	`json`

bash

curl 'https://map-demo.geobridge.cn/geobridge-mapserver/rest/geodata/services/city-roads/MapServer/identify?f=json&geometryType=esriGeometryPoint&geometry=%7B%22x%22%3A116.40%2C%22y%22%3A39.91%7D&sr=4326&mapExtent=116.30,39.85,116.50,40.00&imageDisplay=800,600,96&tolerance=3&layers=visible&token=gb_xxx…'

返回 ArcGIS 风格的 JSON（results 数组），不是 GeoJSON。

find：按文本查找

参数：searchText（要查找的文本）、searchFields（逗号分隔的字段名，不给时查全部字段）、contains（true 为包含匹配，默认；false 为完全匹配）、layers（逗号分隔的图层编号）、sr（输出坐标系）、returnGeometry（默认 true）、f=json。

FeatureServer（要素服务）

地址	说明
`$S/FeatureServer?f=json`	服务元数据与图层列表
`$S/FeatureServer/<图层编号>?f=json`	图层元数据：字段、几何类型、范围等
`$S/FeatureServer/<图层编号>/query`	要素查询
`$S/FeatureServer/<图层编号>/<要素 ID>?f=geojson`	按 ID 取单个要素

query：要素查询

参数	说明
`where`	属性条件，如 `"类型"='主干道'`；`1=1` 表示全部
`outFields`	返回的字段，逗号分隔；`*` 为全部
`returnGeometry`	是否返回几何，默认 `true`
`geometry`	空间条件，ArcGIS JSON 几何，如外包框 `{"xmin":116.3,"ymin":39.8,"xmax":116.5,"ymax":40.0}`
`geometryType`	`esriGeometryEnvelope`、`esriGeometryPoint`、`esriGeometryMultipoint`、`esriGeometryPolyline`、`esriGeometryPolygon`
`spatialRel`	空间关系，如 `esriSpatialRelIntersects`（相交）、`esriSpatialRelContains`、`esriSpatialRelWithin`、`esriSpatialRelEnvelopeIntersects`
`inSR`	`geometry` 的坐标系（EPSG 编号），默认为服务坐标系
`outSR`	输出坐标系，默认为服务坐标系；要经纬度请写 `4326`
`orderByFields`	排序，如 `"长度" DESC`
`objectIds`	逗号分隔的要素 ID
`returnCountOnly`	`true` 时只返回满足条件的数量 `{"count": n}`
`returnIdsOnly`	`true` 时只返回要素 ID
`returnDistinctValues`	`true` 时返回 `outFields` 中字段的唯一值（必须指定具体字段，不能是 `*`）
`resultOffset`	分页起点：跳过的要素个数（非负整数），默认 `0`
`resultRecordCount`	本页最多返回的要素个数（正整数）；超过图层上限时按上限返回，默认即图层上限
`f`	`geojson`（GeoJSON `FeatureCollection`）或 `json`（ArcGIS 风格）

bash

curl 'https://map-demo.geobridge.cn/geobridge-mapserver/rest/geodata/services/city-roads/FeatureServer/0/query?where=1%3D1&outFields=*&outSR=4326&f=geojson&token=gb_xxx…'

单次返回的要素数有上限，可分页：上限由图层的最大要素数决定（未设置时为 1000），图层元数据中的 maxRecordCount 即此值，advancedQueryCapabilities.supportsPagination 为 true。结果被截断（还有更多）时，f=json 的响应顶层带 "exceededTransferLimit": true，f=geojson 的响应在顶层 properties 中带同名字段；增大 resultOffset 继续取下一页，直到它为 false。
分页的次序：不给 orderByFields 时按要素 ID 升序，各页首尾相接；给出时先按它排序（数据库数据源再按主键排序，并列值翻页也稳定）。没有主键的数据库表或 SQL 视图翻页可能重复或遗漏；文件类数据源（如 Shapefile）的深页要从头读到起点，带 orderByFields 时每页都要排序整层，大文件请尽量用条件缩小范围。
resultOffset、resultRecordCount 不是合法的整数时返回 400；orderByFields 中的字段不存在时同样返回 400。
returnCountOnly 返回满足条件的总数，returnIdsOnly 与 returnDistinctValues 也不分页，这三者都忽略 resultOffset、resultRecordCount。

bash

# 按名称排序，每页 100 条，取第 3 页（跳过前 200 条）
curl 'https://map-demo.geobridge.cn/geobridge-mapserver/rest/geodata/services/city-roads/FeatureServer/0/query?where=1%3D1&outFields=名称&orderByFields=名称&resultOffset=200&resultRecordCount=100&f=geojson&token=gb_xxx…'

响应（GeoJSON，节选）：

json

{ "type": "FeatureCollection", "features": [ … ], "properties": { "exceededTransferLimit": true } }

用 JavaScript SDK 时，client.query.allFeatures() 会自动逐页取全，见 SDK 接口参考。

服务发布时设置的基础查询条件始终生效，where 只能在其范围内进一步筛选。
条件很长（例如复杂多边形）时改用 POST 表单提交同样的参数。
字段名中带空格的文件类数据源（如 Shapefile），按该字段过滤可能选不中要素，建议先改字段名。

按 ID 取要素

bash

curl 'https://map-demo.geobridge.cn/geobridge-mapserver/rest/geodata/services/city-roads/FeatureServer/0/42?f=geojson&token=gb_xxx…'

要素 ID 含 % 时会被平台拒绝（400 BAD_PATH）。

VectorTileServer（矢量切片服务）

地址	说明
`$S/VectorTileServer?f=json`	服务元数据
`$S/VectorTileServer/tiles.json`	TileJSON：瓦片地址模板、级别范围、数据范围（`bounds`）、署名
`$S/VectorTileServer/tile/{z}/{y}/{x}.pbf`	矢量瓦片（Mapbox Vector Tile），同样是 `{y}` 在前
`$S/VectorTileServer/resources/styles`	服务的 MapLibre 样式 JSON，可直接作为地图的 `style`
`$S/VectorTileServer/resources/fonts/{fontstack}/{range}.pbf`	样式用到的字形
`$S/VectorTileServer/resources/sprites/<名称>.json`、`.png`	样式用到的雪碧图

服务没有保存样式时，resources/styles 返回按图层生成的默认样式：只含本服务的数据源与图层，不含底图，也没有 sprite。需要底图时请在自己的地图里另行添加。

bash

curl 'https://map-demo.geobridge.cn/geobridge-mapserver/rest/geodata/services/city-roads/VectorTileServer/resources/styles?token=gb_xxx…'

矢量瓦片的 Content-Type 为 application/vnd.mapbox-vector-tile，以 gzip 压缩传输（请求带 Accept-Encoding: gzip 时）。没有数据的位置返回 204。
瓦片包含范围内的全部要素，不受图层「最大记录数」（查询的每页条数）限制。小于约一个像素的要素（线长不足半个瓦片像素、面积不足 1/4 平方瓦片像素）在该级别不输出，几何按瓦片像素精度简化，放大后完整出现。
数据量大的图层有最低输出级别：按数据密度估算一张瓦片要素过多的级别不输出该图层。tiles.json 中图层的 minzoom 就是实际输出的最低级别（服务的 minzoom 为各图层中最小的），MapLibre 不会请求更低级别。
单张瓦片每个图层的要素数另有保护上限（默认读取 20 万、写入 5 万，管理员可调整），正常的城市数据不会触及；超过写入上限时保留面积或长度较大的要素。
请求样式或 tiles.json 时在查询参数里带了 token，返回内容中指向本服务的瓦片、字形、雪碧图地址会自动带上 token；只用请求头时不改写，需要客户端给每个请求加请求头（MapLibre 用 transformRequest）。

WMTS

能力文档：$S/MapServer/WMTS/1.0.0/WMTSCapabilities.xml，也可以用 $S/MapServer/WMTS?SERVICE=WMTS&REQUEST=GetCapabilities。
服务需开启 WMTS。未预切片的服务（含矢量服务）按需出图，提供 GoogleMapsCompatible / WebMercatorQuad（EPSG:3857，与上面的 MapServer 切片相同）、WorldCRS84Quad（经纬度）与 CGCS2000Quad（EPSG:4490）矩阵集，格式为 image/png 与 image/jpeg；启用了预切片的服务按其切片方案提供。
切片地址请从能力文档的 ResourceURL 模板中读取，形如 $S/MapServer/WMTS/tile/1.0.0/<图层>/<样式>/<矩阵集>/{TileMatrix}/{TileRow}/{TileCol}.<扩展名>，同时支持 KVP 方式的 GetTile。
能力文档地址带了 token 时，文档中的切片地址会自动带上 token。GIS 软件中添加 WMTS 连接时，填写能力文档地址即可。
矩阵集、GetFeatureInfo 与 OpenLayers、Cesium、MapLibre 的接入见 WMTS。

地图方案样式

地图方案的公开样式地址：

bash

curl 'https://map-demo.geobridge.cn/geobridge-mapserver/rest/geodata/maps/<方案 id>/style.json?token=gb_xxx…'

返回方案当前版本的 MapLibre 样式，访问级别与地址改写规则见地图方案与工作台。字体与图标的公开地址见字体与图标库。

要素编辑

FeatureServer 另有 addFeatures、updateFeatures、deleteFeatures、applyEdits 编辑接口。它们要求登录且对工作空间有写权限，只接受 POST，API Key 不能用于编辑，见访问级别。

REST 服务 ​

通用约定 ​

服务目录 ​

MapServer（地图服务） ​

切片 ​

export：按范围出图 ​

identify：点击识别 ​

find：按文本查找 ​

FeatureServer（要素服务） ​

query：要素查询 ​

按 ID 取要素 ​

VectorTileServer（矢量切片服务） ​

WMTS ​

地图方案样式 ​

要素编辑 ​

REST 服务

通用约定

服务目录

MapServer（地图服务）

切片

export：按范围出图

identify：点击识别

find：按文本查找

FeatureServer（要素服务）

query：要素查询

按 ID 取要素

VectorTileServer（矢量切片服务）

WMTS

地图方案样式

要素编辑