逐接口字段说明
以下 6 个接口逐一列出请求头、路径参数、查询参数和全部返回字段。每个字段均说明类型、是否必填、默认值、统计含义与示例。
认证、响应与额度
核心指标和最近年鉴版本可匿名预览，响应中的 meta.truncated 会明确标记是否截断。专业会员凭据可读取全部指标、完整历史和二维表格，并通过 X-Rate-Limit-Monthly-Limit 与 X-Rate-Limit-Monthly-Used 查看月度额度。
GET/api/v1/data/metrics/headlines 01核心指标
返回生产总值、人口、研发投入、社会消费品零售总额、每万人执业医师数和用电量。
/api/v1/data/metrics/headlines01核心指标
返回生产总值、人口、研发投入、社会消费品零售总额、每万人执业医师数和用电量。
请求字段
| 字段 | 位置 | 类型 | 必填 | 默认值 | 说明 | 示例 |
|---|---|---|---|---|---|---|
Authorization | 请求头 | string | 是 | — | API 访问凭证。使用 Bearer 方案，格式为 Bearer、一个空格和账户中创建的 sdo_ 开头密钥。 | Bearer sdo_•••••••• |
成功响应字段
| 字段路径 | 类型 | 必有 | 说明 | 示例 |
|---|---|---|---|---|
data | HeadlineMetric[] | 是 | 六项核心指标组成的数组，顺序由服务端固定。 | — |
data[].id | string | 是 | 指标稳定标识，可继续用于单项指标接口。 | gdp |
data[].label | string | 是 | 指标中文标准名称。 | 地区生产总值 |
data[].topic | string | 是 | 指标所属研究主题。 | 经济总量 |
data[].unit | string | 是 | latestValue 和 series[].value 使用的统计单位。 | 亿元 |
data[].latestYear | integer | 是 | 该指标当前最新观测对应的数据年份。 | 2024 |
data[].latestValue | number | 是 | 最新年份的数值，单位见同一对象的 unit。 | 53926.71 |
data[].series | {year,value}[] | 是 | 用于概览图表的年度历史序列。 | — |
data[].series[].year | integer | 是 | 观测对应的数据年份。 | 2024 |
data[].series[].value | number | 是 | 该年份的指标值，单位见 data[].unit。 | 53926.71 |
meta.sourceVersion | string | 是 | 本次响应使用的数据目录版本。保存分析结果时建议同时保存该值，便于日后复现。 | catalog-v1-2026-07-25T10:47:36.391069+00:00 |
meta.generatedAt | string(date-time) | 是 | 当前数据目录生成时间，采用 ISO 8601 格式；它不是客户端请求时间。 | 2026-07-25T10:47:36.391069+00:00 |
GET/api/v1/data/metrics 02指标目录
检索全部可比指标，返回统计区间、主题、单位和观测数量。
/api/v1/data/metrics02指标目录
检索全部可比指标，返回统计区间、主题、单位和观测数量。
请求字段
| 字段 | 位置 | 类型 | 必填 | 默认值 | 说明 | 示例 |
|---|---|---|---|---|---|---|
Authorization | 请求头 | string | 是 | — | API 访问凭证。使用 Bearer 方案，格式为 Bearer、一个空格和账户中创建的 sdo_ 开头密钥。 | Bearer sdo_•••••••• |
q | 查询 | string | 否 | — | 模糊检索指标 ID、中文名称、主题或单位；忽略空白和字母大小写，最长 100 个字符。 | 生产总值 |
topic | 查询 | string | 否 | — | 按研究主题精确筛选，最长 60 个字符；主题值可先从未筛选的指标目录中读取。 | 经济总量 |
limit | 查询 | integer | 否 | 20 | 单页最多返回的目录记录数，范围 1—100。 | 50 |
offset | 查询 | integer | 否 | 0 | 从筛选结果的第几条记录开始返回，从 0 开始。 | 0 |
成功响应字段
| 字段路径 | 类型 | 必有 | 说明 | 示例 |
|---|---|---|---|---|
data | MetricSummary[] | 是 | 当前分页中的指标摘要数组；没有匹配项时为空数组。 | — |
data[].id | string | 是 | 指标的稳定英文标识，用于请求单项时间序列；由小写字母、数字和下划线组成。 | gdp |
data[].label | string | 是 | 指标的中文标准名称。 | 地区生产总值 |
data[].topic | string | 是 | 指标所属研究主题，可直接用于指标目录的 topic 精确筛选。 | 经济总量 |
data[].unit | string | 是 | 时间序列数值统一使用的统计单位；解释 value 时必须同时读取该字段。 | 亿元 |
data[].firstYear | integer | 是 | 当前可比序列中最早的数据年份。 | 1978 |
data[].lastYear | integer | 是 | 当前可比序列中最新的数据年份。 | 2024 |
data[].observationCount | integer | 是 | 完整可比序列包含的观测记录数；在单项接口使用年份筛选后，该值仍描述完整序列。 | 47 |
meta.sourceVersion | string | 是 | 本次响应使用的数据目录版本。保存分析结果时建议同时保存该值，便于日后复现。 | catalog-v1-2026-07-25T10:47:36.391069+00:00 |
meta.generatedAt | string(date-time) | 是 | 当前数据目录生成时间，采用 ISO 8601 格式；它不是客户端请求时间。 | 2026-07-25T10:47:36.391069+00:00 |
pagination.total | integer | 是 | 应用全部筛选条件后的记录总数，不是当前页返回条数。 | 67 |
pagination.limit | integer | 是 | 本次请求采用的单页上限，范围为 1—100。 | 20 |
pagination.offset | integer | 是 | 本次结果在完整结果集中的起始偏移量，从 0 开始。 | 0 |
GET/api/v1/data/metrics/{metricId} 03指标时间序列
读取单项指标的数值、口径信息、年鉴版本和逐年来源链接。
/api/v1/data/metrics/{metricId}03指标时间序列
读取单项指标的数值、口径信息、年鉴版本和逐年来源链接。
请求字段
| 字段 | 位置 | 类型 | 必填 | 默认值 | 说明 | 示例 |
|---|---|---|---|---|---|---|
Authorization | 请求头 | string | 是 | — | API 访问凭证。使用 Bearer 方案，格式为 Bearer、一个空格和账户中创建的 sdo_ 开头密钥。 | Bearer sdo_•••••••• |
metricId | 路径 | string | 是 | — | 指标稳定标识，只能包含小写字母、数字和下划线；可从指标目录的 data[].id 获取。 | gdp |
fromYear | 查询 | integer | 否 | — | 返回区间的起始数据年份，包含该年；范围 1900—2100。 | 2015 |
toYear | 查询 | integer | 否 | — | 返回区间的结束数据年份，包含该年；范围 1900—2100，且不能早于 fromYear。 | 2024 |
成功响应字段
| 字段路径 | 类型 | 必有 | 说明 | 示例 |
|---|---|---|---|---|
data.metric | MetricSummary | 是 | 指标定义及完整可比序列的覆盖范围。 | — |
data.metric.id | string | 是 | 指标的稳定英文标识，用于请求单项时间序列；由小写字母、数字和下划线组成。 | gdp |
data.metric.label | string | 是 | 指标的中文标准名称。 | 地区生产总值 |
data.metric.topic | string | 是 | 指标所属研究主题，可直接用于指标目录的 topic 精确筛选。 | 经济总量 |
data.metric.unit | string | 是 | 时间序列数值统一使用的统计单位；解释 value 时必须同时读取该字段。 | 亿元 |
data.metric.firstYear | integer | 是 | 当前可比序列中最早的数据年份。 | 1978 |
data.metric.lastYear | integer | 是 | 当前可比序列中最新的数据年份。 | 2024 |
data.metric.observationCount | integer | 是 | 完整可比序列包含的观测记录数；在单项接口使用年份筛选后，该值仍描述完整序列。 | 47 |
data.series | MetricObservation[] | 是 | 按年份升序排列的观测数组；应用 fromYear/toYear 后可能为空。 | — |
data.series[].year | integer | 是 | 观测对应的数据年份，不是年鉴出版年份。 | 2024 |
data.series[].value | number | 是 | 该年份的指标数值，单位见 data.metric.unit。 | 53926.71 |
data.series[].geography | string | 是 | 统计地域范围，用于区分全市、区级或其他地域口径。 | 上海市 |
data.series[].priceBasis | string | 是 | 价格口径说明，例如现价、不变价或不适用；跨年计算前应检查该字段是否一致。 | 当年价格 |
data.series[].comparisonSegment | string | 是 | 可比序列分段标识。不同分段可能存在统计制度或口径差异，不宜直接拼接计算。 | 连续口径 |
data.series[].breakId | string | 否 | 口径断点的稳定标识，格式为“指标标识:断点年份”；仅在该观测所属序列存在需要关注的可比性变化时返回。 | exports:1999 |
data.series[].editionYear | integer | 是 | 支持该观测值的年鉴出版年份。 | 2025 |
data.series[].sourcePageId | string | 是 | 该观测值对应的原始年鉴页面标识。 | C0301-51a44e58 |
data.series[].sourceUrl | string(uri) | 是 | 上海市统计局原始年鉴页面地址，用于核对数值、单位和表下注释。 | https://tjj.sh.gov.cn/tjnj/2025tjnj/C0301.htm |
meta.sourceVersion | string | 是 | 本次响应使用的数据目录版本。保存分析结果时建议同时保存该值，便于日后复现。 | catalog-v1-2026-07-25T10:47:36.391069+00:00 |
meta.generatedAt | string(date-time) | 是 | 当前数据目录生成时间，采用 ISO 8601 格式；它不是客户端请求时间。 | 2026-07-25T10:47:36.391069+00:00 |
GET/api/v1/data/yearbooks 04年鉴版本
返回全部年鉴版本、数据年份、原始页数、正式发布表格数、原始识别表格数和单元格数量。
/api/v1/data/yearbooks04年鉴版本
返回全部年鉴版本、数据年份、原始页数、正式发布表格数、原始识别表格数和单元格数量。
请求字段
| 字段 | 位置 | 类型 | 必填 | 默认值 | 说明 | 示例 |
|---|---|---|---|---|---|---|
Authorization | 请求头 | string | 是 | — | API 访问凭证。使用 Bearer 方案，格式为 Bearer、一个空格和账户中创建的 sdo_ 开头密钥。 | Bearer sdo_•••••••• |
成功响应字段
| 字段路径 | 类型 | 必有 | 说明 | 示例 |
|---|---|---|---|---|
data | EditionSummary[] | 是 | 年鉴版本数组，按出版年份从新到旧排列。 | — |
data[].editionYear | integer | 是 | 年鉴出版年份。 | 2025 |
data[].dataYear | integer | 是 | 该版年鉴主要反映的数据年份，通常比出版年份早一年。 | 2024 |
data[].label | string | 是 | 年鉴的完整展示名称。 | 2025 上海统计年鉴 |
data[].isLatest | boolean | 是 | 是否为当前平台收录的最新年鉴版本；数组中只有一个版本为 true。 | true |
data[].pageCount | integer | 是 | 该版年鉴保留的原始内容页数量。 | 558 |
data[].tableCount | integer | 是 | 可以通过表格目录与完整表格接口读取的正式发布表格数。 | 342 |
data[].rawTableCount | integer | 是 | 从原始页面识别出的表格总数，可能包含未进入正式发布目录的内容。 | 504 |
data[].cellCount | integer | 是 | 该版年鉴原始页面中识别并保留的表格单元格记录数，统计范围对应 rawTableCount，不等同于正式发布二维表格的非空值数量。 | 47735 |
meta.sourceVersion | string | 是 | 本次响应使用的数据目录版本。保存分析结果时建议同时保存该值，便于日后复现。 | catalog-v1-2026-07-25T10:47:36.391069+00:00 |
meta.generatedAt | string(date-time) | 是 | 当前数据目录生成时间，采用 ISO 8601 格式；它不是客户端请求时间。 | 2026-07-25T10:47:36.391069+00:00 |
GET/api/v1/data/tables 05表格目录
按标题、年鉴年份、统计年份或章节检索完整年鉴表格。
/api/v1/data/tables05表格目录
按标题、年鉴年份、统计年份或章节检索完整年鉴表格。
请求字段
| 字段 | 位置 | 类型 | 必填 | 默认值 | 说明 | 示例 |
|---|---|---|---|---|---|---|
Authorization | 请求头 | string | 是 | — | API 访问凭证。使用 Bearer 方案，格式为 Bearer、一个空格和账户中创建的 sdo_ 开头密钥。 | Bearer sdo_•••••••• |
q | 查询 | string | 否 | — | 模糊检索表格标题、原始页面标识和章节路径；忽略空白和字母大小写，最长 100 个字符。 | 生产总值 |
editionYear | 查询 | integer | 否 | — | 按年鉴出版年份精确筛选，范围 2004—2100。 | 2025 |
dataYear | 查询 | integer | 否 | — | 筛选 dataYears 中包含指定统计年份的表格，范围 1900—2100。 | 2024 |
chapter | 查询 | string | 否 | — | 在完整章节路径中进行包含匹配，最长 100 个字符。 | 国民经济核算 |
limit | 查询 | integer | 否 | 20 | 单页最多返回的表格目录记录数，范围 1—100。 | 20 |
offset | 查询 | integer | 否 | 0 | 从筛选结果的第几条记录开始返回，从 0 开始。 | 0 |
成功响应字段
| 字段路径 | 类型 | 必有 | 说明 | 示例 |
|---|---|---|---|---|
data | TableSummary[] | 是 | 当前分页中的正式发布表格摘要数组；没有匹配项时为空数组。 | — |
data[].id | string | 是 | 表格稳定标识，由年鉴年份、原始页面标识和页面内表格序号组合而成。 | 2025:C0301-51a44e58:1 |
data[].editionYear | integer | 是 | 年鉴出版年份，例如 2025 表示《2025 上海统计年鉴》。 | 2025 |
data[].dataYear | integer | 是 | 该版年鉴主要对应的数据年份，通常为出版年份的上一年。 | 2024 |
data[].pageId | string | 是 | 原始年鉴页面的稳定标识；与 editionYear、tableNumber 一起用于读取完整表格。 | C0301-51a44e58 |
data[].tableNumber | integer | 是 | 同一原始页面中的表格序号，从 1 开始。 | 1 |
data[].title | string | 是 | 年鉴表格标题，保留原表的主题和年份信息。 | 表3.1 主要年份从业人员 |
data[].chapterPath | string[] | 是 | 表格所在章节路径，按照从上级篇章到具体章节的顺序排列。 | ["第三篇——从业人员和职工工资"] |
data[].dataYears | integer[] | 是 | 从表格内容识别出的统计年份集合；跨年表可能包含多个年份。 | [2000, 2010, 2020, 2024] |
data[].rowCount | integer | 是 | 可读取的数据行数，不包含 columns 表头；与完整表格的 rows.length 一致。 | 28 |
data[].sourceRowCount | integer | 是 | 源 CSV 总行数，包含一行表头，因此通常等于 rowCount + 1。 | 29 |
data[].columnCount | integer | 是 | 表格列数；与完整表格的 columns.length 一致。 | 9 |
data[].sourceUrl | string(uri) | 是 | 上海市统计局原始年鉴页面地址，用于回看原表和核对注释。 | https://tjj.sh.gov.cn/tjnj/2025tjnj/C0301.htm |
data[].sourceSha256 | string | 是 | 表格所在原始年鉴页面内容的 SHA-256 校验值，可用于核对来源版本或判断页面内容是否变化。 | 64 位十六进制字符串 |
meta.sourceVersion | string | 是 | 本次响应使用的数据目录版本。保存分析结果时建议同时保存该值，便于日后复现。 | catalog-v1-2026-07-25T10:47:36.391069+00:00 |
meta.generatedAt | string(date-time) | 是 | 当前数据目录生成时间，采用 ISO 8601 格式；它不是客户端请求时间。 | 2026-07-25T10:47:36.391069+00:00 |
pagination.total | integer | 是 | 应用全部筛选条件后的记录总数，不是当前页返回条数。 | 67 |
pagination.limit | integer | 是 | 本次请求采用的单页上限，范围为 1—100。 | 20 |
pagination.offset | integer | 是 | 本次结果在完整结果集中的起始偏移量，从 0 开始。 | 0 |
GET/api/v1/data/tables/{editionYear}/{pageId}/{tableNumber} 06完整二维表格
返回原始表头、字符串单元格、章节路径、统计年份和来源校验信息。
/api/v1/data/tables/{editionYear}/{pageId}/{tableNumber}06完整二维表格
返回原始表头、字符串单元格、章节路径、统计年份和来源校验信息。
请求字段
| 字段 | 位置 | 类型 | 必填 | 默认值 | 说明 | 示例 |
|---|---|---|---|---|---|---|
Authorization | 请求头 | string | 是 | — | API 访问凭证。使用 Bearer 方案，格式为 Bearer、一个空格和账户中创建的 sdo_ 开头密钥。 | Bearer sdo_•••••••• |
editionYear | 路径 | integer | 是 | — | 年鉴出版年份，范围 2004—2100；应使用表格目录返回的 editionYear。 | 2025 |
pageId | 路径 | string | 是 | — | 原始页面稳定标识，必须以 C 开头且只包含字母、数字和连字符。 | C0301-51a44e58 |
tableNumber | 路径 | integer | 是 | — | 页面内表格序号，从 1 开始。 | 1 |
成功响应字段
| 字段路径 | 类型 | 必有 | 说明 | 示例 |
|---|---|---|---|---|
data.metadata | TableSummary | 是 | 当前表格的目录元数据、行列规模和来源信息。 | — |
data.metadata.id | string | 是 | 表格稳定标识，由年鉴年份、原始页面标识和页面内表格序号组合而成。 | 2025:C0301-51a44e58:1 |
data.metadata.editionYear | integer | 是 | 年鉴出版年份，例如 2025 表示《2025 上海统计年鉴》。 | 2025 |
data.metadata.dataYear | integer | 是 | 该版年鉴主要对应的数据年份，通常为出版年份的上一年。 | 2024 |
data.metadata.pageId | string | 是 | 原始年鉴页面的稳定标识；与 editionYear、tableNumber 一起用于读取完整表格。 | C0301-51a44e58 |
data.metadata.tableNumber | integer | 是 | 同一原始页面中的表格序号，从 1 开始。 | 1 |
data.metadata.title | string | 是 | 年鉴表格标题，保留原表的主题和年份信息。 | 表3.1 主要年份从业人员 |
data.metadata.chapterPath | string[] | 是 | 表格所在章节路径，按照从上级篇章到具体章节的顺序排列。 | ["第三篇——从业人员和职工工资"] |
data.metadata.dataYears | integer[] | 是 | 从表格内容识别出的统计年份集合；跨年表可能包含多个年份。 | [2000, 2010, 2020, 2024] |
data.metadata.rowCount | integer | 是 | 可读取的数据行数，不包含 columns 表头；与完整表格的 rows.length 一致。 | 28 |
data.metadata.sourceRowCount | integer | 是 | 源 CSV 总行数，包含一行表头，因此通常等于 rowCount + 1。 | 29 |
data.metadata.columnCount | integer | 是 | 表格列数；与完整表格的 columns.length 一致。 | 9 |
data.metadata.sourceUrl | string(uri) | 是 | 上海市统计局原始年鉴页面地址，用于回看原表和核对注释。 | https://tjj.sh.gov.cn/tjnj/2025tjnj/C0301.htm |
data.metadata.sourceSha256 | string | 是 | 表格所在原始年鉴页面内容的 SHA-256 校验值，可用于核对来源版本或判断页面内容是否变化。 | 64 位十六进制字符串 |
data.columns | string[] | 是 | 表头单元格数组；元素数量与 data.metadata.columnCount 一致。 | ["指标", "2023", "2024"] |
data.rows | string[][] | 是 | 不含表头的二维数据行；行数与 data.metadata.rowCount 一致。 | [["地区生产总值", "47218.66", "53926.71"]] |
data.rows[][] | string | 是 | 原始单元格文本。数值、空值、千分位空格、脚注符号均以字符串保留，不自动转换类型。 | 53 926.71 |
meta.sourceVersion | string | 是 | 本次响应使用的数据目录版本。保存分析结果时建议同时保存该值，便于日后复现。 | catalog-v1-2026-07-25T10:47:36.391069+00:00 |
meta.generatedAt | string(date-time) | 是 | 当前数据目录生成时间，采用 ISO 8601 格式；它不是客户端请求时间。 | 2026-07-25T10:47:36.391069+00:00 |