datagouv-apis

data.gouv.fr API — 統合リファレンス

3 つの 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/ の意図に対応します。検索結果が見つかったら、MCP 経由、または GET /dataservices/{id}/ 経由で詳細レコード（machine_documentation_url、base_api_url など）を取得してから、上流 API を呼び出してください。エンドポイント：https://mcp.data.gouv.fr/mcp。リポジトリ：datagouv-mcp、datagouv-skill。ツール名はサーバーのバージョンによって異なります。ホストのツール一覧に従い、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 が返した スラッグ、UUID、URL を引用してください。
• 自動化とチャット： MCP は対話型の探索に適しています。再現可能なスクリプトとすべてのルートへのアクセスには Main API が適しています。
• 書き込み（例外的な操作）： X-API-KEY をログに記録したり、表示したりしないでください。ユーザーの明確な意図があり、かつキーが設定されている場合に限り、POST/PUT/PATCH/DELETE を使用してください。401/403 の場合は、キーの不足と権限不足を区別してください。404 の場合は、ID とスラッグを再確認し、検索を使用してください。ここでは、データ提供者向けの一連の処理全体には立ち入りません。

---

API の選択（目的 → API）

ユーザーの目的	使用する API
カタログのメタデータ、リソース、組織、再利用、ディスカッションを検索または読み取る	Main API — 例：GET /datasets/、GET /datasets/{id}/、データセット配下のリソース
Tabular 用にホストされた CSV リソースの行をフィルタリング／並べ替え／ページ分割する	Tabular API — §3 Tabular API の手順を実行した後
プラットフォームの利用状況／統計（dataset、organization、site などのモデル）を確認する	Metrics API — {model} と列フィルターについては Swagger を参照
外部 API を呼び出す（旧カタログ：api.gouv.fr。現在は data.gouv.fr 上の dataservices）	Dataservices — MCP の search_dataservices または GET /dataservices/ を使用し、次に machine_documentation_url と base_api_url を確認します（§1 Main API の手順）

---

識別子とカタログの公開範囲

• 技術的な UUID とスラッグ： 多くのパスではどちらも使用できます。自動化を安定させるため、API レスポンスの UUID を優先してください。
• Tabular の前に解決する： Tabular の {rid} は、GET /datasets/{id}/（または .../resources/）から取得するリソースの UUID です。スラッグしかない場合は、まずデータセットに対して 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/ — テスト専用です。ユーザーからデモを求められた場合を除き、デモの結果を本番環境の事実として提示しないでください。

---

用語集

• データセット： リソースをまとめたカタログ項目（メタデータ、ライセンス、更新頻度、タグ）。
• リソース： データセットに紐付けられたファイルまたは API リンク（CSV、JSON、GeoJSON など）。プラットフォーム上で表形式データとして扱えるファイルの場合、Tabular が使用する ID がそれぞれに割り当てられます。
• 組織／作成者： 公開元の主体です。データセットは組織に所属する場合があります。
• 再利用： プラットフォームのデータセットまたはデータサービスを参照するプロジェクトや記事です。
• データサービス： 文書化された外部 HTTP API（OpenAPI／Swagger のドキュメントが machine_documentation_url にあることがよくあります）で、呼び出しには base_api_url を使用します。以前 api.gouv.fr で参照されていたものと同じ種類の API です。現在は、オープンデータプラットフォームのカタログ項目はデータサービスです。
• スラッグ： URL 内で使用される人が読みやすい ID です。変更されることがあるため、スクリプトでは UUID のほうが安全です。

---

データ作成者向けガイダンス（ドキュメントと公開品質）

ユーザーが、ここにある書き込み API を使用せずに data.gouv.fr で公開するデータの準備、文書化、または法的適格性の確認について尋ねた場合は、公式ガイドに基づいて回答してください（クライアントがページを取得できる場合は取得し、それ以外の場合はリンクを提示してください）：品質ガイド、法務ガイド。このスキルは法律上の助言ではありません。義務やライセンスについては、人による確認を促してください。

---

意図の振り分け（任意）

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 またはスラッグです。技術 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

Organizations

メソッド	パス
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

Dataservices（外部 API）

外部の行政機関または一般向けの HTTP API は、かつて api.gouv.fr に掲載されていました。現在は data.gouv.fr の dataservices として提供されています（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 仕様）、title、description、organization、license などを返します
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

アクセスと認証： 各オブジェクトには access_type（および access_type_reason、authorization_request_url などの関連フィールド）が含まれます。ルールはプラットフォーム全体ではなく、dataservice ごとに定められています。ウェブページ（self_web_url）、business_documentation_url、および上流の OpenAPI に従って、API キー、OAuth、DataPass、その他の認証フローを確認してください。

レート制限： rate_limiting と rate_limiting_url は、外部 API に対する提供元のクォータを示します。Main API の X-RateLimit-* ヘッダーが適用されるのはカタログへのリクエスト（/dataservices/ など）のみであり、base_api_url への呼び出しには適用されません。

一括エクスポート（メタデータ）： GET /site/dataservices.csv は、スプレッドシートやスクリプトで使用できる、dataservice の行をまとめたサイト全体の CSV を返します（JSON リストと同じカタログです）。

OpenAPI が正式な仕様です： ライブ API を呼び出す前に、必ず machine_documentation_url を取得してください。パス、パラメーター、スキーマはその仕様に基づきます。ポータル上の説明文またはこのスキルの内容が、取得した OpenAPI と異なる場合は、OpenAPI を優先してください（§References and freshness の Metrics および Tabular の Swagger にも同じ原則が適用されます）。

dataservice の使用方法： (1) MCP の search_dataservices または GET /dataservices/?q=term で検索します（完了するまで next_page をたどります）。(2) /dataservices/{id}/ を GET し（または MCP の同等機能を使用し）、machine_documentation_url と base_api_url を確認します。(3) machine_documentation_url から OpenAPI 仕様を取得します。(4) その仕様に従って base_api_url を呼び出します。

連絡先、Harvest、ディスカッション、通知

メソッド	パス
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/

投稿、ページ、レポート、移管、アクティビティ、サイト、空間情報、タグ

メソッド	パス
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|illegal_content|others|personal_data|security|spam), subject, message
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 フィールドのスラッグが使用されます。メタデータと ID は引き続き GET レスポンスから取得してください。