API・MCP

基点：https://senkyo-db-290009356139.asia-northeast1.run.app/api/v1 ／ OpenAPI定義

GET /api/v1/dataset
GET /api/v1/districts?election_id=shugiin-2024-10-27&prefecture_code=01
GET /api/v1/districts/{id}
GET /api/v1/candidacies?election_id=shugiin-2024-10-27&q=氏名
GET /api/v1/candidacies/{id}
GET /api/v1/reports/{id}
GET /api/v1/comparisons?candidacy_ids={id1},{id2}

候補者検索はq、prefecture_code、district_id、party_nameで絞り込み、sort、order、page、page_sizeを指定できます。1ページ最大100件です。

認証は不要です。まず収録範囲・選挙ID・データ版を取得し、候補者を検索します。日本語の検索語は--data-urlencodeで指定してください。

curl -fsS 'https://senkyo-db-290009356139.asia-northeast1.run.app/api/v1/dataset'

curl -fsSG 'https://senkyo-db-290009356139.asia-northeast1.run.app/api/v1/candidacies' \
  --data-urlencode 'election_id=shugiin-2024-10-27' \
  --data-urlencode 'q=宮城1区' \
  --data-urlencode 'page_size=100'

page=1から順に、page_size=100で検索し、total_countに達するまでitemsを集めます。取得途中で版が混ざらないよう、最初の応答のdataset_versionを以後の呼び出しにも指定します。HTTP 409が返った場合は、新しい版で最初から取得し直してください。

以下はPython 3の標準ライブラリだけで実行できます。候補者の概要を全件保存します。報告の内訳は候補者のreport_idsを使って/reports/{id}から取得してください。選挙区一覧は/districts?election_id=...で全件返ります。

python3 - <<'PY'
import json
from urllib.parse import urlencode
from urllib.request import urlopen

base = "https://senkyo-db-290009356139.asia-northeast1.run.app/api/v1"

def get(path, **params):
    url = base + path + ('?' + urlencode(params) if params else '')
    with urlopen(url) as response:
        return json.load(response)

info = get('/dataset')
election_id = "shugiin-2024-10-27"
version = info['dataset_version']
items = []
page = 1
while True:
    result = get('/candidacies', election_id=election_id,
                 dataset_version=version, page=page, page_size=100)
    items.extend(result['items'])
    if page * result['page_size'] >= result['total_count']:
        break
    page += 1

with open('candidacies.json', 'w', encoding='utf-8') as output:
    json.dump({'dataset_version': version, 'election_id': election_id,
               'items': items}, output, ensure_ascii=False, indent=2)
print(f'{len(items)}件を candidacies.json に保存しました')
PY

接続URL：https://senkyo-db-290009356139.asia-northeast1.run.app/mcp
トランスポート：Streamable HTTP（ステートレス）

MCP 2026-07-28と、initializeを使う2025-11-25以前のクライアントに対応します。JSONとSSEの両方の応答を受け付けてください。

get_dataset_infoで収録範囲と選挙IDを取得できます。

• get_dataset_info — 収録範囲とデータ版を確認
• list_districts — 選挙区を探す
• get_district — 選挙区の候補者を見る
• search_candidacies — 候補者を検索
• get_candidacy — 候補者の収支と原本を見る
• get_report — 1件の報告を確認
• compare_candidacies — 同じ選挙区の候補者を比較

入力・出力スキーマはtools/listで取得できます。比較できるのは、同じ選挙区の異なる2〜8人です。

対応ブラウザでこのサイトを開くと、上記と同じ7つの読み取りツールをブラウザ内のAIエージェントから利用できます。最初にget_dataset_infoで選挙IDと収録範囲を確認してください。入力・結果・呼び出し頻度の上限はMCPと共通です。

WebMCPは開発中の仕様です。document.modelContextを利用できる環境で登録します。Chromeで試す場合はchrome://flags/#enable-webmcp-testingを有効にして再起動してください。このサイトはOrigin Trialトークンを設定していません。対応状況と試験機能の利用方法はChromeの公式案内をご確認ください。

RESTとMCPを合計し、送信元IPごと・インスタンスごとに60秒間で120回まで利用できます。共有IPの利用者には同じ上限を適用します。超過時はHTTP 429を返すので、Retry-Afterで指定された秒数を待って再試行してください。

502・503・504は回数に上限を設け、待機時間を増やしながら再試行してください。失敗を検索0件や0円として扱わず、取得できなかったことを表示してください。

各応答にschema_versionとdataset_versionを含みます。dataset_versionを指定して呼び出し、版が変わっている場合はHTTP 409 / DATASET_CHANGEDを返します。

金額のamount_yenが未確定ならnullです。known_subtotal_yenは保存された既知の部分合計で、statusとbasisを伴います。report_idsと各事実のsourceから根拠を確認できます。

候補者の公費にはaggregationを含みます。methodはsum（各回の額を合算）、latest（最新の記載された全体額）、unknown（方法不明）。rule_idは設定したルールの識別子、evidenceは判断の根拠です。公費のreport_idsは採用・合算した報告を示し、方法不明の場合は確認対象を示します。最新回が一部未記載・不一致の場合、古い完全な金額へ置き換えません。

HTTP 404はNOT_FOUND、422はINVALID_ARGUMENTまたはINVALID_COMPARISONです。MCPでは同じコードを含むisError: trueのツール結果を返します。検索0件は正常応答です。

現在のデータ版：sha256:45ca10e5d0513d4599438a65a40576670501844f9176c9edf672ef92a57c4b16
スキーマ版：1.5