datagouv-apis

data.gouv.fr API — 综合参考

三个 HTTP API（Main、Metrics、Tabular）以及 dataservices（平台上描述的外部 HTTP API；过去通过 api.gouv.fr 引用，现在是 data.gouv.fr 上的 dataservices）。本文件以使用为主：介绍读取路径和发现方式；仅当用户明确提出要求且有可用的 API 密钥时才进行写入操作。

---

如何使用此技能

• 优先使用 MCP： 如果客户端提供 data.gouv.fr MCP 工具，请用它们以对话方式探索目录；这些工具通过类型化工具调用协调相同的平台功能。尤其对于 dataservices，search_dataservices 的用途与 GET /dataservices/ 相符；找到结果后，在调用上游 API 之前，通过 MCP 或 GET /dataservices/{id}/ 加载详细记录（machine_documentation_url、base_api_url 等）。端点：https://mcp.data.gouv.fr/mcp。代码库：datagouv-mcp、datagouv-skill。工具名称会因服务版本而异——请遵循宿主提供的工具列表；当缺少 MCP 或 MCP 功能不足时，改用本文档中的 HTTP 端点（dataservices：使用 q、过滤条件和 next_page 调用 GET https://www.data.gouv.fr/api/1/dataservices/，然后调用 GET /dataservices/{id}/）。
• 否则使用 HTTP： 使用下方的 Main、Metrics 和 Tabular 基础 URL。优先依据 GET 响应，而非自行假设：不要编造数据集或资源 ID；请引用 API 返回的 slug、UUID 和 URL。
• 自动化与聊天： MCP 适合交互式探索；Main API 适合可重复执行的脚本和完整的路由集合。
• 写入（非典型操作）： 切勿记录或回显 X-API-KEY。仅当用户意图明确且已配置密钥时，才使用 POST/PUT/PATCH/DELETE。遇到 401/403 时，区分密钥缺失和权限不足；遇到 404 时，重新核对 ID 与 slug，并使用搜索。此处不展开完整的数据提供方工作流。

---

选择 API（意图 → 接口）

用户目标	使用
搜索或读取目录元数据、资源、组织、再利用项目、讨论	Main API — 例如 GET /datasets/、GET /datasets/{id}/、数据集下的资源
对托管在 Tabular 上的 CSV 资源的行进行筛选、排序和分页	Tabular API — 按照 §3 Tabular API 中的步骤操作
查看平台使用情况 / 统计数据（模型如 dataset、organization、site）	Metrics API — 查看 Swagger 中的 {model} 和列筛选条件
调用外部 API（旧目录：api.gouv.fr；现为 data.gouv.fr 上的 dataservices）	Dataservices — 使用 MCP search_dataservices 或调用 GET /dataservices/，然后使用 machine_documentation_url + base_api_url（步骤见 §1 Main API）

---

标识符和目录可见性

• 技术 UUID 与 slug： 许多路径中两者均可使用；对于稳定的自动化操作，优先使用 API 响应中的 UUID。
• 使用 Tabular 前先解析： Tabular 的 {rid} 是通过 GET /datasets/{id}/（或 .../resources/）获取的资源 UUID。如果只有 slug，请先对数据集执行 GET，并读取 resources[].id。
• 稳定的资源链接： GET /datasets/r/{id}/ 会重定向到该 ID 对应的最新资源。
• 搜索不等于“整个网络”： GET /datasets/ 支持 archived、deleted、private 等筛选条件。默认设置可能会隐藏部分记录；当用户需要完整信息且密钥权限允许时，请显式设置查询参数。

---

分页和速率限制

• 列表会返回 data、page、page_size、total、next_page、previous_page。请持续跟进 next_page，直到其为空，而不要猜测页数。
• 使用合理的 page_size；避免频繁请求服务，也不要在没有必要时逐页下载整个目录。
• 遵守 X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset：剩余量较低时，请降低请求频率或采用退避策略。

---

演示环境与生产环境

• 生产环境： https://www.data.gouv.fr/api/1/（以及下文的生产环境 Metrics / Tabular 主机）。
• 演示环境： https://demo.data.gouv.fr/api/1/ — 仅用于测试；除非用户要求演示结果，否则不要将演示结果作为生产环境事实呈现。

---

术语表

• 数据集（Dataset）： 目录条目（元数据、许可证、更新频率、标签），包含多个资源。
• 资源（Resource）： 附加到数据集的文件或 API 链接（CSV、JSON、GeoJSON 等）；如果文件在平台上兼容表格格式，每个资源都有一个供 Tabular 使用的 ID。
• 组织 / 数据生产者： 发布实体；数据集可以属于某个组织。
• 复用（Reuse）： 引用了平台数据集或数据服务的项目或文章。
• 数据服务（Dataservice）： 有文档说明的外部 HTTP API（OpenAPI/Swagger 文档通常位于 machine_documentation_url），调用时使用 base_api_url。这类 API 过去曾在 api.gouv.fr 上列出；如今开放数据平台目录中的条目称为数据服务。
• Slug： URL 中便于人类阅读的 ID；可能会变化；脚本使用 UUID 更安全。

---

数据生产者指导（文档与发布质量）

当用户询问如何准备、记录数据或确定数据的法律属性以便发布到 data.gouv.fr，且不使用此处的写入 API 时，请以官方指南为依据（如果客户端允许，请获取页面；否则提供链接）：质量指南、法律指南。此技能不提供法律建议；请建议用户就义务和许可事宜进行人工审核。

---

意图路由（可选）

flowchart LR
  subgraph discovery [Discovery]
    A[CatalogMetadata]
    B[RowQueries]
    C[UsageStats]
    D[ExternalAPI]
  end
  A --> MainAPI[MainAPI]
  B --> TabularAPI[TabularAPI]
  C --> MetricsAPI[MetricsAPI]
  D --> Dataservices[DataservicesThenUpstream]

---

1. 主 API

基础 URL： https://www.data.gouv.fr/api/1/ | 演示环境：https://demo.data.gouv.fr/api/1/

身份验证： 读取公开。写入（POST/PUT/PATCH/DELETE）：请求头 X-API-KEY。权限 = web（组织成员才能编辑组织数据集）。草稿使用 private: true。ID： 技术 ID 或 slug；优先使用技术 ID。内容： JSON；文件上传：multipart/form-data。可选： 使用 X-Fields 限制返回字段。

响应： 分页列表包含：data、page、page_size、total、next_page、previous_page。错误：400、401、403、404、410、423、500、502。响应正文：{"message":"..."}。速率限制：X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset。

数据集

方法	路径
GET	/datasets/ — q、page、page_size、sort、organization、owner、tag、license、format、geozone、granularity、temporal_coverage、schema、topic、archived、deleted、private
POST	/datasets/ — title、description、frequency、last_update、organization/owner、license、tags、private
GET/PUT/DELETE	/datasets/{id}/
GET	/datasets/{id}/resources/
POST	/datasets/{id}/resources/ — 创建
PUT	/datasets/{id}/resources/ — 重新排序（正文：数组）
GET/PUT/DELETE	/datasets/{id}/resources/{rid}/
POST	/datasets/{id}/resources/{rid}/upload/ 或 /datasets/{id}/upload/
POST/DELETE	/datasets/{id}/badges/、/datasets/{id}/badges/{badge_kind}/
POST/DELETE	/datasets/{id}/featured/
GET/POST/DELETE	/datasets/{id}/followers/
GET	/datasets/{id}/rdf、/datasets/{id}/rdf.{_format}
GET/POST/...	/datasets/community_resources/、.../{community}/、.../upload/
GET	/datasets/badges/、frequencies/、licenses/、resource_types/、extensions/、schemas/
GET	/datasets/suggest/、suggest/formats/、suggest/mime/ — q、size
GET	/datasets/r/{rid} — 将资源下载为文件
GET	/datasets/recent.atom

组织

方法	路径
GET/POST	/organizations/
GET/PUT/DELETE	/organizations/{id}/
POST/PUT/DELETE	/organizations/{id}/member/{user}/ — 角色：admin
GET/POST	/organizations/{id}/membership/, .../accept/{id}/, .../refuse/{id}/
GET	/organizations/{id}/datasets/, reuses/, discussions/, contacts/, contacts/suggest/
GET	/organizations/{id}/datasets.csv, dataservices.csv, datasets-resources.csv, discussions.csv
GET	/organizations/{id}/catalog, catalog.{_format}
GET/POST/DELETE	/organizations/badges/, {id}/badges/, {id}/badges/{badge_kind}/
POST/PUT	/organizations/{id}/logo/
GET	/organizations/roles/, suggest/
GET/POST/DELETE	/organizations/{id}/followers/

用户

方法	路径
GET/POST	/users/
GET/PUT/DELETE	/users/{id}/
POST	/users/{id}/avatar/
GET	/users/{id}/contacts/
GET	/users/roles/, suggest/
GET/POST/DELETE	/users/{id}/followers/

我（已通过身份验证）

方法	路径
GET/PUT/DELETE	/me/
DELETE/POST	/me/apikey/
POST	/me/avatar/
GET	/me/datasets/, reuses/, metrics/, org_datasets/, org_reuses/, org_community_resources/, org_discussions/

复用项目

方法	路径
GET/POST	/reuses/ — q, organization, owner, tag, topic, type, dataset, featured
GET/PUT/DELETE	/reuses/{id}/
POST	/reuses/{id}/datasets/, dataservices/
GET/POST/DELETE	/reuses/badges/, {id}/badges/, {id}/featured/
POST	/reuses/{id}/image/
GET	/reuses/topics/, types/, suggest/
GET/POST/DELETE	/reuses/{id}/followers/
GET	/reuses/recent.atom

数据服务（外部 API）

过去，外部行政或公共 HTTP API 会列在 api.gouv.fr 上；现在，它们以 data.gouv.fr 上的数据服务形式呈现（GET /dataservices/，对象字段如下）。

方法	路径
GET/POST	/dataservices/ — GET：q、page、page_size、organization、owner、topic、tag、access_type、featured、dataset、sort
GET/PATCH/DELETE	/dataservices/{id}/ — GET 返回 base_api_url、machine_documentation_url（OpenAPI/Swagger 规范）、标题、描述、组织、许可证等。
POST	/dataservices/{id}/datasets/ — 请求体：[{id}]
DELETE	/dataservices/{id}/datasets/{dataset}/
POST/DELETE	/dataservices/{id}/featured/
GET	/dataservices/{id}/rdf、rdf.{_format}
GET/POST/DELETE	/dataservices/{id}/followers/
GET	/dataservices/recent.atom

访问和身份验证： 每个对象都包含 access_type（以及 access_type_reason、authorization_request_url 等相关字段）。规则针对每项数据服务单独设定，而非全平台通用：请参考网页（self_web_url）、business_documentation_url 以及上游 OpenAPI，了解 API 密钥、OAuth、DataPass 或其他流程。

速率限制： rate_limiting 和 rate_limiting_url 描述外部 API 提供方的配额。主 API 的 X-RateLimit-* 标头仅适用于目录请求（/dataservices/ 等），不适用于你对 base_api_url 发起的调用。

批量导出（元数据）： GET /site/dataservices.csv 会返回涵盖全站数据服务条目的 CSV，可用于电子表格或脚本（与 JSON 列表使用相同的目录）。

OpenAPI 是权威依据： 调用在线 API 前，务必先获取 machine_documentation_url。路径、参数和架构均以该规范为准；如果门户上的人工撰写文本或此技能与获取到的 OpenAPI 不一致，请以 OpenAPI 为准（与 §参考资料和时效性 中的 Metrics 和 Tabular Swagger 采用相同原则）。

使用数据服务： (1) 查找数据服务：使用 MCP search_dataservices 或 GET /dataservices/?q=term（持续跟进 next_page，直到没有下一页）。(2) GET /dataservices/{id}/（或使用对应的 MCP 操作）获取 machine_documentation_url 和 base_api_url。(3) 获取 machine_documentation_url 中的 OpenAPI 规范。(4) 按照该规范调用 base_api_url。

联系人、收割、讨论和通知

方法	路径
POST	/contacts/ — 姓名、电子邮件、角色
GET	/contacts/roles/
GET/PUT/DELETE	/contacts/{id}/
GET/POST	/harvest/sources/
GET/PUT/DELETE	/harvest/source/{id}/
GET	/harvest/source/{id}/jobs/、/harvest/job/{ident}/
POST	/harvest/source/{id}/run/
POST/DELETE	/harvest/source/{id}/schedule/
GET/POST	/harvest/source/{id}/preview/、/harvest/source/preview/
POST	/harvest/source/{id}/validate/
GET	/harvest/backends/
GET/POST/PUT/DELETE	/discussions/、discussions/{id}/
POST	/discussions/{id}/ — 评论、关闭（请求体）
PUT/DELETE	/discussions/{id}/comments/{idx}/
DELETE	/discussions/{id}/comments/{idx}/spam/、discussions/{id}/spam/
GET	/notifications/
POST	/notifications/{id}/read/

帖子、页面、报告、转移、活动、站点、空间、标签

方法	路径
GET/POST	/posts/ — name、content、body_type、kind、datasets、reuses
GET/PUT/DELETE	/posts/{id}/
POST/PUT	/posts/{id}/image/
POST/DELETE	/posts/{id}/publish/
GET	/posts/recent.atom
GET/POST	/pages/
GET/PUT	/pages/{id}/
GET/POST	/reports/ — reason（explicit_content
GET	/reports/reasons/
GET/PATCH	/reports/{id}/
GET/POST	/transfer/、transfer/{id}/ — subject、recipient、comment；响应：accept|refuse
GET	/activity/ — user、organization、related_to
GET/PATCH	/site/
GET	/site/catalog、catalog.{_format}、context.jsonld、data.{_format}
GET	/site/datasets.csv、dataservices.csv、reuses.csv、organizations.csv、resources.csv、harvests.csv、tags.csv
GET	/access_type/reason_categories/
GET	/avatars/{identifier}/{size}/
GET	/spatial/granularities/、levels/、coverage/{level}/、zone/{id}/、zone/{id}/datasets/、zones/{ids}/、zones/suggest/
GET	/tags/suggest/
GET	/spam/
GET	/proconnect/auth、login/、logout、logout_oauth
GET/POST	/workers/jobs/
GET/PUT/DELETE	/workers/jobs/{id}/
GET	/workers/jobs/schedulables/、workers/tasks/{id}/

---

2. 指标 API

基础 URL： https://metric-api.data.gouv.fr | Swagger：https://metric-api.data.gouv.fr/api/doc

方法	路径	描述
GET	/api/{model}/data/	分页的指标行（JSON）。参数：page、page_size、column__sort、column__exact、column__contains、column__less、column__greater
GET	/api/{model}/data/csv/	将 {model} 的指标导出为 CSV（适用时与 JSON 使用相同的列筛选条件；不是 Tabular API 资源 CSV 格式）
GET	/health/	健康检查

{model} = 表名（例如 site、organization、dataset）。模型和列请参阅 Swagger。

---

3. Tabular API

基础 URL： https://tabular-api.data.gouv.fr | Swagger：https://tabular-api.data.gouv.fr/api/doc | 单个资源：GET /api/resources/{rid}/swagger/

{rid} = 来自主 API 的资源 UUID（数据集的资源）。

Tabular 数据工作流（按顺序使用）：

1. GET /api/resources/{rid}/ — 确认资源已公开，并获取链接。
2. GET /api/resources/{rid}/profile/ — 列类型、统计信息、索引。
3. GET /api/resources/{rid}/swagger/ — 每列允许的查询参数和运算符（复杂筛选前请先阅读）。
4. GET /api/resources/{rid}/data/ — page 和 page_size（最大值为 50）。如需聚合，请先检查 /api/aggregation-exceptions/（只有列出的资源/列可能支持 groupby/count/sum 等操作）。

方法	路径	描述
GET	/api/resources/{rid}/	元数据、指向 profile/data/swagger 的链接
GET	/api/resources/{rid}/profile/	列类型、格式、统计信息、索引
GET	/api/resources/{rid}/swagger/	数据端点的 OpenAPI（列、运算符）
GET	/api/aggregation-exceptions/	允许聚合的资源 UUID
GET	/api/resources/{rid}/data/	筛选、排序、分页（page、page_size 最大值为 50）
GET	/api/resources/{rid}/data/csv/	流式传输 CSV
GET	/api/resources/{rid}/data/json/	流式传输 JSON
GET	/health/	健康检查

数据参数： columns=col1,col2 | 筛选：column__exact、__differs、__isnull、__isnotnull、__contains、__notcontains、__in、__notin、__less、__greater、__strictly_less、__strictly_greater | 排序：column__sort=asc|desc | 聚合（允许的资源、已索引的列）：column__groupby、__count、__avg、__min、__max、__sum。JSON 列：仅支持 isnull/isnotnull。

---

快速示例

import requests

BASE = "https://www.data.gouv.fr/api/1"

# 1) Search catalog, then open first hit
r = requests.get(f"{BASE}/datasets/", params={"q": "transport", "page_size": 5}).json()
first = r["data"][0]
ds = requests.get(f"{BASE}/datasets/{first['id']}/").json()

# 2) Pick a CSV resource UUID, then Tabular profile + data (use any resource id exposed by Tabular)
csvs = [res for res in ds["resources"] if res.get("format", "").lower() == "csv"]
rid = csvs[0]["id"] if csvs else ds["resources"][0]["id"]
requests.get(f"https://tabular-api.data.gouv.fr/api/resources/{rid}/profile/").json()
requests.get(
    f"https://tabular-api.data.gouv.fr/api/resources/{rid}/data/",
    params={"page": 1, "page_size": 20},
).json()

# 3) Direct file download (when you need the raw file, not row filtering)
url = next(res["url"] for res in ds["resources"] if res["id"] == rid)
requests.get(url, stream=True)

# Metrics API — paginated dataset metrics (models/columns in Swagger)
requests.get(
    "https://metric-api.data.gouv.fr/api/dataset/data/",
    params={"page": 1, "page_size": 20},
).json()

Python 客户端： https://github.com/etalab/datagouv-client-python

---

参考资料与时效性

• 主 API Swagger（权威路径）： https://www.data.gouv.fr/api/1/swagger.json
• 指标 / 表格： 使用上方链接的 Swagger。如果某个路径或参数与本文档不一致，以实时 Swagger 为准。
• API 指南（面向读者，技术内容）： 上手指南、API 参考、下载目录、SPARQL。

与他人分享时，www.data.gouv.fr 上的数据集页面使用 API 字段中的 slug；元数据和 ID 仍应从 GET 响应中获取。