OGC API

平台为每个服务提供 OGC API 接口：Common（landing 页、一致性声明、OpenAPI 文档）、Features（Part 1 Core、Part 2 CRS、Part 3 Filtering，CQL2 文本）、Tiles（矢量瓦片与地图瓦片）与 Maps（按范围出图）。响应为 JSON 或 HTML，浏览器可以直接逐级浏览。启用方式与 API Key 的通用规则见 OGC 服务概览。

地址与启用

发布时勾选 OGC API（不默认勾选），Features、Tiles、Maps 共用这一开关。矢量、栅格图层与切片包都可以。
根地址：https://map-demo.geobridge.cn/geobridge-mapserver/rest/geodata/services/<服务路径>/ogcapi（…/ogcapi 与 …/ogcapi/ 都可以）。注意它直接挂在服务路径之下，不在 MapServer 之下。
只有 GET。未启用或服务不存在时为 404，服务已停止为 503。
所有错误都是 application/problem+json（RFC 7807），访问被拒绝（401、403）时也是：

json

{ "type": "about:blank", "title": "Unauthorized", "status": 401, "detail": "该服务需要 API Key", "code": "TOKEN_REQUIRED" }

code 为平台错误码或 OGC 异常码，detail 为说明。

通用约定

格式：f=json 或 f=html；不带 f 时按 Accept 请求头选择（浏览器得到 HTML，*/* 或不带 Accept 得到 JSON）。要素另接受 f=geojson，瓦片与地图用 f=mvt|png|jpeg。
链接：每个 JSON 文档都带 links（self、alternate，以及 next、items、tiles 等），客户端沿链接导航即可。
API Key：地址后加 token=gb_xxx…（参数名不区分大小写）时，文档中的每个链接（含 next、prev 与瓦片地址模板）都会带上 token；也可以用请求头 X-GeoBridge-Token。
参数名区分大小写，不认识的参数为 400（不支持的参数：…）。

Common

端点（相对于 `…/ogcapi`）	说明
`/`	landing 页：标题、描述与各入口链接
`/conformance`	一致性声明，见一致性
`/api`	OpenAPI 3.0 文档；`/api.html` 为引用它的说明页
`/collections`	集合列表
`/collections/{collectionId}`	集合描述：范围、可用坐标系（`crs`）、存储坐标系（`storageCrs`）与链接

要素集合：每个可查询的矢量图层一个，id 与 WFS 类型名相同但不带 gb: 前缀（见名称规则），有 items。
其他集合：栅格等其余图层也列为集合，只有地图与瓦片，没有 items。
中文 id 在地址中需要百分号编码（浏览器与大多数 HTTP 库会自动处理）。

Features

端点	说明
`/collections/{collectionId}/items`	要素（GeoJSON 或 HTML 表格）
`/collections/{collectionId}/items/{featureId}`	单个要素
`/collections/{collectionId}/queryables`	可查询属性（JSON Schema）

要素 id 与 WFS 中 <类型名>.<要素 ID> 的后半部分相同。只输出、只能查询图层「输出字段」中的字段（与 WFS 相同）。

items 参数

参数	规则
`limit`	缺省 10；上限为图层的最大要素数（未设置时 1000），大于上限时按上限返回
`offset`	0–1,000,000；超过总数时为空集合
`bbox`	`minx,miny,maxx,maxy`（或含高程的 6 个数），按 `bbox-crs` 的官方轴序；经纬度下西边界大于东边界表示跨越 180° 经线
`bbox-crs`	`bbox` 的坐标系，缺省 CRS84
`datetime`	时刻（`2024-01-05`、`2024-01-05T08:00:00Z`）或区间 `a/b`（`..` 为开放端），作用在集合的第一个日期时间字段；没有日期时间字段的集合忽略该条件
`crs`	输出坐标系，缺省 CRS84；响应带 `Content-Crs` 头
`filter`	CQL2 文本过滤条件，见下文
`filter-lang`	只接受 `cql2-text`（缺省即是）
`filter-crs`	`filter` 中几何的坐标系，缺省 CRS84
`<字段名>=<值>`	属性等值过滤，字段为 queryables 中列出的字段；与上面的参数同名的字段请在 `filter` 中写

各条件与服务发布时设置的基础查询条件取交集。单个要素只接受 f、crs、token。
分页：有下一页时给 rel="next" 的链接，offset > 0 时给 prev。响应只有 numberReturned，没有 numberMatched（不做计数查询）。翻页的稳定性同 WFS 分页。

bash

O='https://map-demo.geobridge.cn/geobridge-mapserver/rest/geodata/services/city-roads/ogcapi'
curl "$O/collections?f=json"
curl "$O/collections/道路_线/items?f=json&limit=100&bbox=116.3,39.8,116.5,40.0"
curl -G "$O/collections/道路_线/items" --data-urlencode "filter=等级 IN (1,2) AND 名称 LIKE '长安%'" -d f=json

CQL2

类别	支持
基本	`AND`、`OR`、`NOT`、括号；`=`、`<>`、`<`、`>`、`<=`、`>=`；`IS [NOT] NULL`；字符串、数值、`TRUE`/`FALSE`、`DATE('2024-01-05')`、`TIMESTAMP('2024-01-05T08:00:00Z')`
高级比较	`[NOT] LIKE`（`%`、`_`）、`[NOT] BETWEEN … AND …`、`[NOT] IN (…)`
空间	`S_INTERSECTS`、`S_EQUALS`、`S_DISJOINT`、`S_TOUCHES`、`S_WITHIN`、`S_OVERLAPS`、`S_CROSSES`、`S_CONTAINS`；几何字面量为 WKT 或 `BBOX(…)`

关键字不区分大小写；属性名可以用双引号（"名称"）。属性名只能是 queryables 中的字段与 geometry。
不支持任何函数（CASEI、ACCENTI、T_* 时间函数、A_* 数组函数等，返回 400「过滤条件不支持函数」）、算术表达式与 CQL2 JSON。
最长 64 KiB，嵌套不超过 32 层，条件合计不超过 500 个（IN 的每个值算一个）。

坐标系

每个集合的 crs：CRS84（缺省）、EPSG:4326、EPSG:3857、EPSG:4490，再加服务坐标系；storageCrs 为服务坐标系。
坐标一律按坐标系的官方轴序：CRS84 经度在前；EPSG:4326、4490 纬度在前；3857 东、北。bbox、filter 中的坐标与输出都如此。
参数中写 http://www.opengis.net/def/crs/EPSG/0/3857，也接受 EPSG:3857、[EPSG:3857] 与 URN 写法；不在列表中的坐标系为 400。

瓦片

端点（相对于 `…/ogcapi`）	说明
`/tileMatrixSets`、`/tileMatrixSets/{tileMatrixSetId}`	矩阵集列表与定义（OGC 2D-TMS 2.0 JSON）
`/tiles`、`/tiles/{tileMatrixSetId}`	数据集瓦片集列表与元数据：有矢量瓦片时为矢量瓦片，没有时同地图瓦片
`/tiles/{tileMatrixSetId}/{tileMatrix}/{tileRow}/{tileCol}`	数据集瓦片
`/map/tiles`、`/map/tiles/{tileMatrixSetId}`、`…/{tileMatrix}/{tileRow}/{tileCol}`	数据集地图瓦片（PNG / JPEG）
`/collections/{collectionId}/tiles…`、`/collections/{collectionId}/map/tiles…`	集合瓦片，结构同上：矢量瓦片只含该图层，地图瓦片只画该图层

服务	地图瓦片	矢量瓦片（MVT）
按需出图	`WebMercatorQuad`（0–24 级）、`WorldCRS84Quad`（0–20）、`CGCS2000Quad`（0–20）；PNG、JPEG；整体与每个集合	服务开启了 VectorTileServer（切片格式 pbf、切片方案 xyz）时：`WebMercatorQuad` 0–22 级，整体与每个矢量集合
预切片	按切片方案推导的矩阵集与同网格的内置矩阵集；切片配置的格式；只有整体	同上

瓦片集元数据给出 dataType（vector 或 map）、坐标系、tileMatrixSetLimits（每个可用级别的行列范围）、经纬度范围、矢量瓦片的图层列表，以及瓦片地址模板（rel="item"、templated: true，每种格式一个）。
范围之外、没有列出的级别为 404；空的矢量瓦片为 204。瓦片带 ETag，内容未变时返回 304。
格式：f=mvt|png|jpeg，或按 Accept；缺省为该瓦片集的第一种格式。数据集瓦片另支持 collections=a,b，只包含（或只画）这些集合（预切服务不支持）。
WebMercatorQuad 的 {tileMatrix}/{tileRow}/{tileCol} 就是 XYZ 的 {z}/{y}/{x}，同一位置的地图瓦片与 WMTS、TMS、MapServer 切片内容相同。

地图（Maps）

/map 为整个服务的地图，/collections/{collectionId}/map 为单个集合的地图。

参数	规则
`f`	`png`（缺省）或 `jpeg`
`crs`	输出坐标系，缺省 CRS84；可选值同集合的 `crs`，数据重投影到该坐标系出图
`bbox` + `bbox-crs`	范围，按 `bbox-crs`（缺省 CRS84）的官方轴序
`subset` + `subset-crs`	如 `Lon(113.8:114.4),Lat(22.1:22.6)`（也接受 `E`/`N`、`x`/`y`；端点 `*` 或缺省的轴取服务范围）
`center` + `center-crs`	中心点，配合 `scale-denominator` 与宽高
`width`、`height`	1–4096；只给一个时另一个按范围的宽高比；都不给时长边 1024
`scale-denominator`	按 0.28 mm 像素换算宽高；不能与 `bbox` 同时给出宽高
`transparent`	缺省 `true`（JPEG 恒为不透明）
`bgcolor`	`RRGGBB`、`0xRRGGBB`、`#RRGGBB` 或颜色名；不透明时生效

bbox、subset、center 只能给一个；都不给时为服务范围。
响应头 Content-Crs、Content-Bbox 给出实际的坐标系与范围；因比例尺省略的图层列在 X-GeoBridge-Omitted-Layers 中。

bash

curl -o map.png 'https://map-demo.geobridge.cn/geobridge-mapserver/rest/geodata/services/city-basemap/ogcapi/map?bbox=113.8,22.1,114.4,22.6&width=1024&f=png'

一致性

/conformance 按服务的实际内容声明：

总是：Common（core、landing-page、oas30、html、json）；Maps（core、dataset-map、collection-map、background、scaling、spatial-subsetting、crs、png、jpeg）。
有要素集合时：Features Part 1（core、oas30、html、geojson）、Part 2（crs）、Part 3（queryables、queryables-query-parameters、filter、features-filter）、CQL2（cql2-text、basic-cql2、advanced-comparison-operators、basic-spatial-functions、basic-spatial-functions-plus、spatial-functions）。
有瓦片时：Tiles（core、tileset、tilesets-list、geodata-tilesets、dataset-tilesets、oas30 与实际的 mvt、png、jpeg；支持 collections 参数时另有 geodata-selection），2D-TMS 2.0 的矩阵集、矩阵集范围与瓦片集元数据的 JSON 编码。

客户端示例

QGIS（要素）：图层 → 添加图层 → 添加 WFS / OGC API - Features 图层，新建连接，URL 填 …/ogcapi/，版本选「OGC API - Features」。API Key 级别在 URL 后加 ?token=gb_xxx…。

GDAL

bash

O='https://map-demo.geobridge.cn/geobridge-mapserver/rest/geodata/services/city-roads/ogcapi'
# 要素：列出集合、读取、过滤
ogrinfo "OAPIF:$O/"
ogrinfo -al -q -where "等级 = 1" "OAPIF:$O/" 道路_线
ogr2ogr -f GPKG roads.gpkg "OAPIF:$O/" 道路_线
# 地图与地图瓦片（GDAL 3.8）
gdalinfo -oo API=MAP "OGCAPI:$O/collections/道路_线"
gdal_translate -oo API=TILES -oo TILEMATRIXSET=WorldCRS84Quad -outsize 1024 0 "OGCAPI:$O/collections/道路_线" roads.png
# API Key 级别
ogrinfo "OAPIF:$O/?token=gb_xxx…"

MapLibre（矢量瓦片）：用瓦片集元数据中的模板，WebMercatorQuad 的 {tileMatrix}/{tileRow}/{tileCol} 换成 {z}/{y}/{x}。

map.addSource('roads', {
  type: 'vector',
  tiles: ['https://map-demo.geobridge.cn/geobridge-mapserver/rest/geodata/services/city-roads/ogcapi/tiles/WebMercatorQuad/{z}/{y}/{x}?f=mvt'],
  maxzoom: 22,
})
map.addLayer({ id: 'roads', type: 'line', source: 'roads', 'source-layer': '<MVT 图层名>', paint: { 'line-color': '#c0392b' } })

MVT 图层名见瓦片集元数据的 layers。JS SDK 的 maplibre.addOgcApiTiles() 会读元数据、取模板并生成默认样式；地图瓦片用 kind: 'map'。

OpenLayers（要素）：读 items 的 GeoJSON。

import VectorLayer from 'ol/layer/Vector'
import VectorSource from 'ol/source/Vector'
import GeoJSON from 'ol/format/GeoJSON'

const layer = new VectorLayer({
  source: new VectorSource({
    url: 'https://map-demo.geobridge.cn/geobridge-mapserver/rest/geodata/services/city-roads/ogcapi/collections/道路_线/items?f=json&limit=1000',
    format: new GeoJSON(),
  }),
})

一次最多取图层的每页上限条，要沿 next 读完请用 JS SDK 的 openlayers.ogcApiVectorSource() 或 ogcApi.allItems()。

已知限制

集合的空间范围是服务的经纬度范围，不按图层统计；时间范围写为开放区间。
没有 numberMatched；不支持排序（sortby）、属性选择（properties）、CQL2 JSON 与函数。
datetime 只作用在第一个日期时间字段，没有日期时间字段的集合忽略它。
offset 最大 1,000,000，之后不再给 next。
矢量瓦片只有 WebMercatorQuad，且要求服务开启 VectorTileServer、切片方案为 xyz。
预切服务的地图瓦片只有整体，没有集合瓦片与 collections 选择；集合仍可出地图。
没有样式（styles）、时间等维度的子集，没有 GeoTIFF 与 GeoJSON 瓦片；WebP 只在 WMTS 中提供。
按需出图的瓦片按服务范围声明行列范围：服务配置的范围小于数据时，范围外的瓦片为 404。

OGC API ​

地址与启用 ​

通用约定 ​

Common ​

Features ​

items 参数 ​

CQL2 ​

坐标系 ​

瓦片 ​

地图（Maps） ​

一致性 ​

客户端示例 ​

已知限制 ​

OGC API

地址与启用

通用约定

Common

Features

items 参数

CQL2

坐标系

瓦片

地图（Maps）

一致性

客户端示例

已知限制