Imported from etalab-ia/skills (skills/datagouv-apis/SKILL.md). Install upstream with npx skills add etalab-ia/skills --skill datagouv-apis. Copyright stays with the author.

data.gouv.fr APIs — Consolidated Reference

Three HTTP APIs (Main, Metrics, Tabular) plus dataservices (external HTTP APIs described on the platform; they used to be referenced on api.gouv.fr and are now dataservices on data.gouv.fr). This file is consumption-first: read paths and discovery; writes only when the user explicitly wants them and an API key is available.

How to use this skill

• MCP first: If the client exposes data.gouv.fr MCP tools, use them for conversational catalog exploration; they orchestrate the same platform capabilities with typed tool calls. For dataservices in particular, search_dataservices matches the intent of GET /dataservices/; after a hit, load the detail record (machine_documentation_url, base_api_url, etc.) via MCP or via GET /dataservices/{id}/ before calling the upstream API. Endpoint: https://mcp.data.gouv.fr/mcp. Repos: datagouv-mcp, datagouv-skill. Tool names vary by server version—follow the host’s tool list and fall back to the HTTP endpoints in this document when MCP is missing or insufficient (dataservices: GET https://www.data.gouv.fr/api/1/dataservices/ with q, filters, and next_page, then GET /dataservices/{id}/).
• HTTP otherwise: Use the Main, Metrics, and Tabular base URLs below. Prefer GET responses over assumptions: do not invent dataset or resource IDs; cite slugs, UUIDs, and URLs returned by the API.
• Automation vs chat: MCP suits interactive exploration; the Main API suits reproducible scripts and the full route surface.
• Writes (atypical): Never log or echo X-API-KEY. Use POST/PUT/PATCH/DELETE only with clear user intent and a configured key. On 401/403, distinguish missing key from insufficient permissions; on 404, re-check id vs slug and use search. Do not expand into full producer pipelines here.

Choosing an API (intent → surface)

Identifiers and catalog visibility

• Technical UUID vs slug: Both work in many paths; prefer the UUID from API responses for stable automation.
• Resolve before Tabular: Tabular {rid} is the resource UUID from GET /datasets/{id}/ (or .../resources/). If you only have a slug, GET the dataset first and read resources[].id.
• Stable resource link: GET /datasets/r/{id}/ redirects to the latest resource for that id.
• Search is not “the whole web”: GET /datasets/ supports filters such as archived, deleted, private. Defaults may hide some records; set query params explicitly when the user needs a full picture and the key allows it.

Pagination and rate limits

• Lists return data, page, page_size, total, next_page, previous_page. Follow next_page until empty instead of guessing page counts.
• Use a reasonable page_size; avoid hammering the service or downloading the entire catalog page by page without need.
• Respect X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset: slow down or backoff when remaining is low.

Demo vs production

• Production: https://www.data.gouv.fr/api/1/ (and production Metrics / Tabular hosts below).
• Demo: https://demo.data.gouv.fr/api/1/ — for tests only; do not present demo results as production facts unless the user asked for demo.

Glossary

• Dataset: A catalog entry (metadata, licence, frequency, tags) grouping resources.
• Resource: A file or API link attached to a dataset (CSV, JSON, GeoJSON, etc.); each has an id used by Tabular when the file is tabular-compatible on the platform.
• Organization / producer: Publisher entity; datasets may belong to an organization.
• Reuse: A project or article that references platform datasets or dataservices.
• Dataservice: A documented external HTTP API (OpenAPI/Swagger often at machine_documentation_url) with a base_api_url for calls. Same class of APIs that were once referenced on api.gouv.fr; the catalog entry on the open data platform is now a dataservice.
• Slug: Human-readable id in URLs; may change; UUID is safer for scripts.

Producer coaching (documentation and publication quality)

When the user asks how to prepare, document, or legally qualify data for publication on data.gouv.fr without using write APIs here, ground answers in the official guides (fetch pages if the client allows, otherwise give links): Guide qualité, Guide juridique. This skill is not legal advice; encourage human review for obligations and licensing.

Intent routing (optional)

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. Main API

Base URL: https://www.data.gouv.fr/api/1/ | Demo: https://demo.data.gouv.fr/api/1/

Auth: Read public. Write (POST/PUT/PATCH/DELETE): header X-API-KEY. Permissions = web (org member to edit org datasets). private: true for drafts. IDs: technical id or slug; prefer technical id. Content: JSON; file uploads: multipart/form-data. Optional: X-Fields to limit returned fields.

Response: Paginated lists: data, page, page_size, total, next_page, previous_page. Errors: 400, 401, 403, 404, 410, 423, 500, 502. Body: {"message":"..."}. Rate limits: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Datasets

Organizations

Users

Me (authenticated)

Reuses

Dataservices (external APIs)

External administrative or public HTTP APIs were historically listed on api.gouv.fr; they are now represented as dataservices on data.gouv.fr (GET /dataservices/, object fields below).

Access and auth: Each object includes access_type (and related fields such as access_type_reason, authorization_request_url). Rules are per dataservice, not platform-wide: follow the web page (self_web_url), business_documentation_url, and the upstream OpenAPI for API keys, OAuth, DataPass, or other flows.

Rate limits: rate_limiting and rate_limiting_url describe producer quotas on the external API. The Main API’s X-RateLimit-* headers apply only to catalog requests (/dataservices/, etc.), not to calls you make to base_api_url.

Bulk export (metadata): GET /site/dataservices.csv returns a site-wide CSV of dataservice rows for spreadsheets or scripts (same catalog as the JSON list).

OpenAPI is authoritative: Always fetch machine_documentation_url before calling the live API. Paths, parameters, and schemas come from that spec; if human text on the portal or this skill disagrees with the fetched OpenAPI, trust the OpenAPI (same principle as Metrics and Tabular Swaggers in §References and freshness).

To use a dataservice: (1) Find it: MCP search_dataservices or GET /dataservices/?q=term (follow next_page until done). (2) GET /dataservices/{id}/ (or the MCP equivalent) for machine_documentation_url and base_api_url. (3) Fetch machine_documentation_url for the OpenAPI spec. (4) Call base_api_url per that spec.

Contacts, Harvest, Discussions, Notifications

Posts, Pages, Reports, Transfer, Activity, Site, Spatial, Tags

2. Metrics API

Base URL: https://metric-api.data.gouv.fr | Swagger: https://metric-api.data.gouv.fr/api/doc

{model} = table name (e.g. site, organization, dataset). See Swagger for models and columns.

3. Tabular API

Base URL: https://tabular-api.data.gouv.fr | Swagger: https://tabular-api.data.gouv.fr/api/doc | Per-resource: GET /api/resources/{rid}/swagger/

{rid} = resource UUID from main API (dataset's resources).

Tabular data workflow (use in order):

1. GET /api/resources/{rid}/ — confirm the resource is exposed and get links.
2. GET /api/resources/{rid}/profile/ — column types, stats, indexes.
3. GET /api/resources/{rid}/swagger/ — allowed query params and operators per column (read before complex filters).
4. GET /api/resources/{rid}/data/ — page and page_size (max 50). For aggregations, check /api/aggregation-exceptions/ first (only listed resources/columns may support groupby/count/sum, etc.).

Data params: columns=col1,col2 | Filter: column__exact, __differs, __isnull, __isnotnull, __contains, __notcontains, __in, __notin, __less, __greater, __strictly_less, __strictly_greater | Sort: column__sort=asc|desc | Aggregation (allowed resources, indexed cols): column__groupby, __count, __avg, __min, __max, __sum. JSON columns: only isnull/isnotnull.

Quick examples

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 client: https://github.com/etalab/datagouv-client-python

References and freshness

• Main API Swagger (authoritative paths): https://www.data.gouv.fr/api/1/swagger.json
• Metrics / Tabular: use their Swaggers linked above. If a path or parameter disagrees with this file, trust the live Swagger.
• API guide (human, technical): Prise en main, Référence API, Télécharger le catalogue, SPARQL.

For sharing with humans, dataset pages on www.data.gouv.fr use slugs from API fields; metadata and ids should still come from GET responses.