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/