{ "openapi": "3.1.0", "info": { "title": "历史地名服务 · 数据接口", "version": "0.1.2", "summary": "历史地名服务的数据接口，输出格式与 CHGIS 复旦大学版本保持一致。", "description": "本服务仅供研究与教学使用，不是 CHGIS 官方站点。数据来自 CHGIS 项目 2019 年 2 月发布的版本（CC BY-NC 4.0，署名、非商业性使用，不得用于商业用途）。\n\n原版网站：哈佛大学 https://chgis.hudci.org/tgaz/ ；复旦大学 https://tgaz.fudan.edu.cn/tgaz/indexAPI.html 。\n\n**默认行为**：数据接口（`/tgaz/...`）与复旦大学版本一致，使用前缀匹配、不做繁简转换；网页界面（`/`、`/search`、`/place/{sys_id}`）默认使用子串匹配并自动匹配简体、繁体与异体字。\n\n**限流**：正常浏览不受影响；请求过快会收到 `429` 与 `Retry-After` 响应头。", "license": { "name": "CC BY-NC 4.0", "url": "https://creativecommons.org/licenses/by-nc/4.0/" }, "contact": { "name": "历史地名服务", "url": "https://tgaz.cckb.cn/" } }, "servers": [ { "url": "https://tgaz.cckb.cn", "description": "本站" } ], "tags": [ { "name": "地名记录", "description": "按记录编号取一条完整记录" }, { "name": "检索", "description": "按地名、年份、类别、资料来源组合检索" }, { "name": "服务信息", "description": "服务自述与健康检查" } ], "paths": { "/tgaz/placename/{format}/{sys_id}": { "get": { "tags": [ "地名记录" ], "summary": "取一条地名记录", "operationId": "getPlacename", "parameters": [ { "$ref": "#/components/parameters/RecordFormat" }, { "$ref": "#/components/parameters/SysId" } ], "responses": { "200": { "description": "记录内容。内容类型随 `format` 变化（`json` 用 `text/json`，与线上一致）。示例：https://tgaz.cckb.cn/tgaz/placename/json/hvd_41237 text/html：HTML；text/xml：XML（内容类型与线上一致，用 text/xml）", "content": { "text/json": { "schema": { "$ref": "#/components/schemas/PlacenameDocument" } }, "text/turtle": { "schema": { "type": "string" } }, "application/geo+json": { "schema": { "type": "object" } }, "text/html": { "schema": { "type": "string" } }, "text/xml": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/ParameterError" }, "404": { "$ref": "#/components/responses/NotFound" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/tgaz/placename": { "get": { "tags": [ "检索" ], "summary": "按条件检索地名", "operationId": "searchPlacenames", "parameters": [ { "$ref": "#/components/parameters/SearchFormat" }, { "$ref": "#/components/parameters/Name" }, { "$ref": "#/components/parameters/Year" }, { "$ref": "#/components/parameters/FeatureType" }, { "$ref": "#/components/parameters/Source" }, { "$ref": "#/components/parameters/Parent" }, { "$ref": "#/components/parameters/Identifier" }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/Match" }, { "$ref": "#/components/parameters/Variants" } ], "responses": { "200": { "description": "命中列表。JSON/XML 最多返回 200 条，HTML 每页 50 条；JSON 的内容类型与线上一致（`text/json`）。示例：https://tgaz.cckb.cn/tgaz/placename?fmt=json&n=Tianbao text/html：HTML；text/xml：XML（内容类型与线上一致，用 text/xml）", "content": { "text/json": { "schema": { "$ref": "#/components/schemas/SearchDocument" } }, "text/html": { "schema": { "type": "string" } }, "text/xml": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/ParameterError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/tgaz/service-info": { "get": { "tags": [ "服务信息" ], "summary": "服务自述", "description": "返回服务的名称、版本、说明与数据许可（内容与复旦大学版本一致）。", "operationId": "getServiceInfo", "responses": { "200": { "description": "服务自述。示例：https://tgaz.cckb.cn/tgaz/service-info", "content": { "text/json": { "schema": { "$ref": "#/components/schemas/ServiceInfo" } } } } } } }, "/healthz": { "get": { "tags": [ "服务信息" ], "summary": "健康检查", "description": "检查服务与只读数据文件是否可用。健康时返回 `{\"status\":\"ok\"}`。", "operationId": "getHealth", "responses": { "200": { "description": "服务可用。", "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "version": { "type": "string" } } }, "examples": { "ok": { "value": { "status": "ok", "version": "0.1.0" } } } } } }, "503": { "$ref": "#/components/responses/Unavailable" } } } } }, "components": { "parameters": { "RecordFormat": { "name": "format", "in": "path", "required": true, "description": "输出形态。", "schema": { "type": "string", "enum": [ "json", "xml", "html", "rdf", "esgar", "typedjson", "geojson" ], "default": "json" }, "example": "json" }, "SysId": { "name": "sys_id", "in": "path", "required": true, "description": "记录编号，例如 `hvd_41237`、`hgr_719`、`TBRC_G1KR100`。比较时忽略大小写与尾随空格。", "schema": { "type": "string" }, "example": "hvd_41237" }, "SearchFormat": { "name": "fmt", "in": "query", "description": "输出形态。默认 `html`；`json`/`xml` 是给程序用的格式（与复旦大学版本一致）。`typedjson` 与 `geojson` 是本站新增。", "schema": { "type": "string", "enum": [ "json", "xml", "html", "typedjson", "geojson" ], "default": "html" }, "example": "json" }, "Name": { "name": "n", "in": "query", "description": "地名。默认按前缀匹配；以 `$` 结尾表示整串精确匹配；`match=contains` 时按子串匹配。", "schema": { "type": "string" }, "example": "Tianbao" }, "Year": { "name": "yr", "in": "query", "description": "年份（公元纪年，公元前用负数）。只返回该年份处于存续期内的记录。", "schema": { "type": "integer" }, "example": 1911 }, "FeatureType": { "name": "ftyp", "in": "query", "description": "功能类型，可填中文（县、州）或转写（xian）。比较时忽略大小写与声调。", "schema": { "type": "string" }, "example": "xian" }, "Source": { "name": "src", "in": "query", "description": "资料来源。", "schema": { "type": "string", "enum": [ "CHGIS", "TBRC", "HGR" ] }, "example": "CHGIS" }, "Parent": { "name": "p", "in": "query", "description": "上级单位的地名（前缀匹配）。", "schema": { "type": "string" }, "example": "Chuzhou" }, "Identifier": { "name": "id", "in": "query", "description": "记录编号。给出后优先于 `n`。", "schema": { "type": "string" }, "example": "hvd_41237" }, "Page": { "name": "pg", "in": "query", "description": "页码（只在 `fmt=html` 时生效，从 1 开始）。", "schema": { "type": "integer", "minimum": 1, "default": 1 }, "example": 1 }, "Match": { "name": "match", "in": "query", "description": "本站新增：`prefix`（默认）、`contains`（子串）、`exact`（整串）。未知取值按默认处理。", "schema": { "type": "string", "enum": [ "prefix", "contains", "exact" ], "default": "prefix" }, "example": "prefix" }, "Variants": { "name": "variants", "in": "query", "description": "本站新增：`1` 时同时匹配简体、繁体与异体写法（召回只增不减，不会漏掉默认行为能命中的记录）。", "schema": { "type": "string", "enum": [ "0", "1" ], "default": "0" }, "example": "0" } }, "responses": { "ParameterError": { "description": "参数不合法（例如未知的输出形态）。", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "NotFound": { "description": "记录不存在。兼容层按原版行为返回 HTML 错误页。", "content": { "text/html": { "schema": { "type": "string" } } } }, "Unavailable": { "description": "服务或数据文件暂时不可用。", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "schemas": { "Problem": { "type": "object", "required": [ "type", "title", "status", "detail" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" } } }, "PlacenameDocument": { "type": "object", "additionalProperties": false, "description": "一条记录的完整内容，字段名与复旦大学版本一致（含未转义控制字符的注记按 JSON 规范转义，见 docs/old-api-behavior.md 差异 #1）。", "required": [ "system", "license", "uri", "sys_id" ], "properties": { "system": { "type": "string" }, "license": { "type": "string" }, "uri": { "type": "string" }, "sys_id": { "type": "string" }, "sys_id of alternate": { "type": "string" }, "spellings": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/Spelling" } }, "feature_type": { "$ref": "#/components/schemas/FeatureType" }, "temporal": { "$ref": "#/components/schemas/Temporal" }, "spatial": { "$ref": "#/components/schemas/Spatial" }, "historical_context": { "$ref": "#/components/schemas/HistoricalContext" }, "data source": { "type": "string" }, "source note": { "type": [ "string", "null" ] }, "source uri": { "type": [ "string", "null" ] } } }, "Spelling": { "type": "object", "additionalProperties": false, "required": [ "written form" ], "properties": { "written form": { "type": "string" }, "script": { "type": [ "string", "null" ] }, "exonym language": { "type": [ "string", "null" ] }, "transcribed in": { "type": [ "string", "null" ] }, "attested by": { "type": [ "string", "null" ] }, "note": { "type": [ "string", "null" ] } } }, "SearchDocument": { "type": "object", "additionalProperties": false, "required": [ "system", "count of displayed results", "count of total results", "placenames" ], "properties": { "system": { "type": "string" }, "memo": { "type": "string" }, "count of displayed results": { "type": "string" }, "count of total results": { "type": "string" }, "placenames": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/SearchResult" } } } }, "SearchResult": { "type": "object", "additionalProperties": false, "required": [ "sys_id", "uri" ], "properties": { "sys_id": { "type": "string" }, "uri": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "transcription": { "type": [ "string", "null" ] }, "years": { "type": [ "string", "null" ] }, "parent sys_id": { "type": [ "string", "null" ] }, "parent name": { "type": [ "string", "null" ] }, "feature type": { "type": [ "string", "null" ] }, "object type": { "type": [ "string", "null" ] }, "xy coordinates": { "type": [ "string", "null" ] }, "data source": { "type": [ "string", "null" ] } } }, "ServiceInfo": { "type": "object", "additionalProperties": false, "required": [ "service name", "version no.", "description" ], "properties": { "service name": { "type": "string" }, "version no.": { "type": "string" }, "description": { "type": "string" }, "size": { "type": "string" }, "funding from": { "type": "array", "items": { "type": "string" } }, "license": { "type": "string" } } }, "FeatureType": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": [ "string", "null" ] }, "alternate name": { "type": [ "string", "null" ] }, "transcription": { "type": [ "string", "null" ] }, "English": { "type": [ "string", "null" ] } } }, "Temporal": { "type": "object", "additionalProperties": false, "properties": { "begin": { "type": [ "string", "null" ] }, "begin rule": { "type": [ "string", "null" ] }, "end": { "type": [ "string", "null" ] }, "end rule": { "type": [ "string", "null" ] } } }, "Spatial": { "type": "object", "additionalProperties": false, "properties": { "object_type": { "type": [ "string", "null" ] }, "xy_type": { "type": [ "string", "null" ] }, "latitude": { "type": [ "string", "null" ] }, "longitude": { "type": [ "string", "null" ] }, "source": { "type": [ "string", "null" ] }, "present_location": { "type": [ "array", "null" ], "items": { "type": "object", "additionalProperties": false, "properties": { "country code": { "type": [ "string", "null" ] }, "text": { "type": [ "string", "null" ] }, "source": { "type": [ "string", "null" ] }, "attestation": { "type": [ "string", "null" ] } } } } } }, "HistoricalContext": { "type": "object", "additionalProperties": false, "description": "上下级与沿革关系。三种关系的元素字段名不同（`part of` 用 `begin year`/`parent id`；`subordinate units` 用 `begin_year`/`child id`），这里按原样描述。", "properties": { "part of": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/ParentRelation" } }, "subordinate units": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/ChildRelation" } }, "preceded by": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/PrecededByRelation" } } } }, "GeoJSONFeatureCollection": { "type": "object", "additionalProperties": false, "required": [ "type", "features" ], "properties": { "type": { "type": "string", "enum": [ "FeatureCollection" ] }, "features": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "type", "geometry", "properties" ], "properties": { "type": { "type": "string", "enum": [ "Feature" ] }, "geometry": { "type": [ "object", "null" ], "description": "零坐标视为无位置，此时为 null。", "properties": { "type": { "type": "string" }, "coordinates": { "type": "array" } } }, "properties": { "type": "object" } } } } } }, "ParentRelation": { "type": "object", "additionalProperties": false, "properties": { "begin year": { "type": [ "string", "null" ] }, "end year": { "type": [ "string", "null" ] }, "parent id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "transcribed": { "type": [ "string", "null" ] } } }, "ChildRelation": { "type": "object", "additionalProperties": false, "properties": { "begin_year": { "type": [ "string", "null" ] }, "end_year": { "type": [ "string", "null" ] }, "child id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "transcribed": { "type": [ "string", "null" ] } } }, "PrecededByRelation": { "type": "object", "additionalProperties": false, "properties": { "preceded by id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "transcribed": { "type": [ "string", "null" ] } } }, "PlacenameDocumentTyped": { "type": "object", "additionalProperties": false, "description": "与 PlacenameDocument 同键同形，但可定类型的值输出为数字（年份、判定依据、经纬度）。", "required": [ "system", "license", "uri", "sys_id" ], "properties": { "system": { "type": "string" }, "license": { "type": "string" }, "uri": { "type": "string" }, "sys_id": { "type": "string" }, "sys_id of alternate": { "type": "string" }, "spellings": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/Spelling" } }, "feature_type": { "$ref": "#/components/schemas/FeatureType" }, "temporal": { "$ref": "#/components/schemas/TemporalTyped" }, "spatial": { "$ref": "#/components/schemas/SpatialTyped" }, "historical_context": { "$ref": "#/components/schemas/HistoricalContext" }, "data source": { "type": "string" }, "source note": { "type": [ "string", "null" ] }, "source uri": { "type": [ "string", "null" ] } } }, "TemporalTyped": { "type": "object", "additionalProperties": false, "properties": { "begin": { "type": [ "integer", "null" ] }, "begin rule": { "type": [ "integer", "null" ] }, "end": { "type": [ "integer", "null" ] }, "end rule": { "type": [ "integer", "null" ] } } }, "SpatialTyped": { "type": "object", "additionalProperties": false, "properties": { "object_type": { "type": [ "string", "null" ] }, "xy_type": { "type": [ "string", "null" ] }, "latitude": { "type": [ "number", "null" ] }, "longitude": { "type": [ "number", "null" ] }, "source": { "type": [ "string", "null" ] }, "present_location": { "type": [ "array", "null" ], "items": { "type": "object", "additionalProperties": false, "properties": { "country code": { "type": [ "string", "null" ] }, "text": { "type": [ "string", "null" ] }, "source": { "type": [ "string", "null" ] }, "attestation": { "type": [ "string", "null" ] } } } } } }, "SearchDocumentTyped": { "type": "object", "additionalProperties": false, "required": [ "system", "count of displayed results", "count of total results", "placenames" ], "properties": { "system": { "type": "string" }, "memo": { "type": "string" }, "count of displayed results": { "type": "integer" }, "count of total results": { "type": "integer" }, "placenames": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/SearchResult" } } }, "description": "与 SearchDocument 同键同形，但两个计数是数字。" } }, "examples": { "CanonicalJSON": { "summary": "一条真实记录（hvd_41237）", "externalValue": "https://tgaz.cckb.cn/tgaz/placename/json/hvd_41237" }, "CanonicalXML": { "summary": "同一条记录的 XML（hvd_41237）", "externalValue": "https://tgaz.cckb.cn/tgaz/placename/xml/hvd_41237" }, "SearchJSON": { "summary": "检索 Tianbao（前缀匹配）", "externalValue": "https://tgaz.cckb.cn/tgaz/placename?fmt=json&n=Tianbao" }, "ServiceInfo": { "summary": "服务自述", "externalValue": "https://tgaz.cckb.cn/tgaz/service-info" } } } }