data.gouv.fr APIs — Consolidated Reference

Three APIs: Main (catalog), Metrics (usage), Tabular (CSV rows). Prefer the data.gouv.fr MCP server tools when configured; endpoints below apply with or without MCP.

---

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

Method	Path
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/ — create
PUT	/datasets/{id}/resources/ — reorder (body: array)
GET/PUT/DELETE	/datasets/{id}/resources/{rid}/
POST	/datasets/{id}/resources/{rid}/upload/ or /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/{id} — redirect to latest resource
GET	/datasets/recent.atom

Organizations

Method	Path
GET/POST	/organizations/
GET/PUT/DELETE	/organizations/{id}/
POST/PUT/DELETE	/organizations/{id}/member/{user}/ — role: 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/

Users

Method	Path
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/

Me (authenticated)

Method	Path
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/

Reuses

Method	Path
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

Dataservices (external APIs)

Method	Path
GET/POST	/dataservices/ — GET: q, page, page_size, organization, owner, topic, tag, access_type, featured, dataset, sort
GET/PATCH/DELETE	/dataservices/{id}/ — GET returns base_api_url, machine_documentation_url (OpenAPI/Swagger spec), title, description, organization, license, etc.
POST	/dataservices/{id}/datasets/ — body: [{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

To use a dataservice: (1) Search /dataservices/?q=term to find it. (2) GET /dataservices/{id}/ to get machine_documentation_url and base_api_url. (3) Fetch machine_documentation_url to get OpenAPI spec with endpoints/params. (4) Make calls to base_api_url per spec.

Contacts, Harvest, Discussions, Notifications

Method	Path
POST	/contacts/ — name, email, role
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}/ — comment, close (body)
PUT/DELETE	/discussions/{id}/comments/{idx}/
DELETE	/discussions/{id}/comments/{idx}/spam/, discussions/{id}/spam/
GET	/notifications/
POST	/notifications/{id}/read/

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

Method	Path
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; response: 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. Metrics API

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

Method	Path	Description
GET	/api/{model}/data/	Paginated metrics (JSON). Params: page, page_size, column__sort, column__exact, column__contains, column__less, column__greater
GET	/api/{model}/data/csv/	Same as CSV stream (no pagination)
GET	/health/	Health check

{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).

Method	Path	Description
GET	/api/resources/{rid}/	Metadata, links to profile/data/swagger
GET	/api/resources/{rid}/profile/	Column types, formats, stats, indexes
GET	/api/resources/{rid}/swagger/	OpenAPI for data endpoint (columns, operators)
GET	/api/aggregation-exceptions/	Resource UUIDs allowed for aggregation
GET	/api/resources/{rid}/data/	Filter, sort, paginate (page, page_size max 50)
GET	/api/resources/{rid}/data/csv/	Stream CSV
GET	/api/resources/{rid}/data/json/	Stream JSON
GET	/health/	Health check

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

# Main API — search datasets
requests.get("https://www.data.gouv.fr/api/1/datasets/", params={"q": "transport", "page_size": 20}).json()

# Metrics API
requests.get("https://metric-api.data.gouv.fr/api/dataset/data/", params={"page": 1}).json()

# Tabular API — resource data
requests.get(f"https://tabular-api.data.gouv.fr/api/resources/{resource_id}/data/", params={"page": 1, "page_size": 20}).json()

Python client: https://github.com/etalab/datagouv-client-python
Main API Swagger: https://www.data.gouv.fr/api/1/swagger.json
Guides: https://guides.data.gouv.fr/guide-data.gouv.fr/readme-1/reference/