civiq

CIV.IQ

政府機関の情報源から得た市民向けのインテリジェンスを、一般の人が利用しやすい形に整理します。

civdotiq.org • API リファレンス • 貢献する • ライセンス

---

これは何ですか

市民向けのインテリジェンスプラットフォームです。住所を入力すると、連邦および州の代表者を、採決記録、連邦選挙資金、委員会の所属、立法活動、政治資金の動向に関する機械学習を活用した分析とともに確認できます。地方自治体（市・郡）は対象外です。地方の記録には共通規格も一元的な情報源もないため、CIV.IQ は検証済みの公開情報源が存在する場合に限り、追加する予定です。

データは政府の公式記録から取得しています。大半は各機関の API または一括データファイルから直接読み込んでいます。州議会の OpenStates や、解析済みの STOCK Act 提出書類を扱う Congress Trading Monitor など、名称のあるオープンデータセットを介して取得するものもあります。分析はすべて統計に基づき、信頼度スコアと手法を公開しています。データを利用できない場合は、インターフェースとレスポンスのペイロードで明示します。データを捏造することはありません。

正確な対象範囲を示す一覧は、docs/COVERAGE.md をご覧ください。「CIV.IQ が実際に扱う情報は何か」という問いへの正式な回答です。この README にあるその他の説明は、すべてこのページに準拠します。

機能

議員：連邦および州の議員について、写真、連絡先情報、委員会の所属、投票記録を提供します。

選挙資金：連邦のみです。FECへの献金、PACの支出、支出の追跡、寄付者の業種分析を提供します。州の選挙資金情報は現在利用できません（FollowTheMoney.orgはOpenSecretsとの統合に伴い、メンテナンスモードになっています）。

インテリジェンスレイヤー：投票記録と選挙資金、ロビー活動の届出、株式取引、委員会の管轄を相互参照する統計分析ツールにより、影響力の可能性を示すパターンを明らかにします。各分析結果には、信頼度スコア、手法に関する注記、相関関係は因果関係を意味しないという免責事項が付記されます。

資金レポート：住所に基づいて検索し、選挙献金から委員会の所属、立法上の結果までの流れを、お住まいの地域の議員について追跡します。

規制と意見募集期間：連邦官報と連携し、規則案、最終規則、大統領令、意見募集中の案件を提供します。

州議会：OpenStatesを通じて全50州に対応し、議員、法案、委員会、会期日程を提供します。議員別の投票履歴は現在準備中です。州議会選挙区7,383か所すべてを対象に、インタラクティブな選挙区境界マップを提供します。州レベルの選挙資金、ロビー活動、株式取引のデータは、州の対応範囲に含まれません。

地方自治体：対象外です（市・郡）。地方の記録には共通規格や一元的な情報源がないため、CIV.IQでは、検証済みの公開情報源が存在する場合に限り、追加を予定しています。

選挙区インテリジェンス：人口統計、経済指標（BLSの雇用データ）、連邦支出（USASpending）、インフラ指標、および各連邦議会選挙区との関連度順に並べた法案を提供します。

Nostrへの公開：法案の新規提出、投票、公聴会などの市民関連イベントに署名し、分散型で検証可能な配信のため、Nostrネットワークに公開します。

開発者向け連携機能

連携機能	提供内容
OpenAPI仕様	39個のエンドポイント、38個のスキーマ — あらゆる言語でクライアントを生成できます
@civiq/sdk	依存関係ゼロのTypeScriptクライアント（npm install @civiq/sdk）
MCPサーバー	AIアシスタント向けの46個のツール（Claude、Cursorなど）
Atomフィード	法案、議員、選挙区、委員会のRSS互換フィード
埋め込みウィジェット	議員カード、選挙区検索、法案の状況を表示する埋め込み用HTML
llms.txt	AIが検出できるドキュメント

データソース

ソース	提供するデータ
Congress.gov v3	法案、議員、委員会、公聴会
FEC.gov	選挙資金の献金、支出、PAC の届出
U.S. Census Bureau	ジオコーディング、人口統計、選挙区の境界（TIGER）
Senate.gov XML	上院本会議の投票、投票記録
House Clerk XML	下院の投票記録
GovInfo	公聴会の議事録、立法文書
Federal Register	大統領令、規則案、意見募集期間
USASpending.gov v2	連邦政府の契約、助成金、選挙区別の受賞情報
LDA (lda.gov)	ロビー活動の開示届出
Bureau of Labor Statistics	雇用、賃金、労働力データ
SEC EDGAR	企業の届出
FRED	連邦準備制度の経済指標
Regulations.gov	規則案に対するパブリックコメント
OpenStates (オープンデータセット)	州議会議員、法案、委員会（全50州）
Congress Trading Monitor (オープンデータセット)	両院のSTOCK法取引記録。下院と上院の公式届出から解析
Wikidata (オープンデータセット)	州の行政トップ、州司法機関

この表には主なソースを記載しています。その他の連邦政府機関のデータセット（CDC PLACES、CMS、FEMA、FBI、FDIC、VA、Treasury、CFPB、NHTSA、EPA、College Scorecard など）が、選挙区およびインテリジェンス機能を支えています。CIV.IQ は合計 40のデータソース（政府機関29、オープンデータセット11） を読み込みます。全リストと集計ルールについては、docs/COVERAGE.mdをご覧ください。

データを捏造したり生成したりすることはありません。ソースを利用できない場合は、その旨を応答で伝えます。

セットアップ

git clone https://github.com/civdotiq/civ.iq.git
cd civ.iq
npm install
cp .env.example .env.local

.env.local に API キーを追加します。すべて無料です。

# Required
CONGRESS_API_KEY=       # api.congress.gov/sign-up
FEC_API_KEY=            # api.open.fec.gov/developers
CENSUS_API_KEY=         # api.census.gov/data/key_signup.html
OPENSTATES_API_KEY=     # openstates.org/accounts/profile

# Recommended
UPSTASH_REDIS_REST_URL= # upstash.com (caching)
UPSTASH_REDIS_REST_TOKEN=
GOOGLE_GENERATIVE_AI_API_KEY= # aistudio.google.com/apikey (AI summaries)

# Optional (enhanced features)
FRED_API_KEY=           # fredaccount.stlouisfed.org/apikeys
DATA_GOV_API_KEY=       # api.data.gov/signup (Regulations.gov)
GOVINFO_API_KEY=        # api.govinfo.gov/docs

Nostr での公開と ActivityPub 連携を含む全リストについては、.env.example をご覧ください。

npm run dev

localhost:3000/api/health で動作を確認します。

構成

src/
├── app/
│   ├── api/                  # API routes (public contract: /api/v1 + openapi.json)
│   └── (civic)/              # Pages (representatives, districts, legislation, etc.)
├── components/
│   ├── intelligence/         # Insight cards, leaderboards, influence chains
│   └── ...                   # Shared UI, search, visualizations
├── features/                 # Feature modules
│   ├── campaign-finance/
│   ├── legislation/
│   ├── representatives/
│   └── state-legislature/
├── lib/
│   ├── intelligence/         # Analyzers, ML models, embeddings, entity resolution
│   ├── nostr/                # Nostr event signing and relay publishing
│   ├── data-sources/         # Federal Register, FRED, SEC, lobbying services
│   └── ...                   # API clients, services, utilities
├── hooks/                    # Custom React hooks
└── types/                    # TypeScript definitions
packages/
├── sdk/                      # @civiq/sdk (TypeScript API client)
├── civic-statistics/         # @civiq/civic-statistics (confidence scoring, correlation)
└── entity-resolution/        # @civiq/entity-resolution (entity matching, deduplication)

技術スタック

Next.js 16、React 18、TypeScript（strict）、Tailwind CSS、SWR、Zustand、MapLibre GL、D3.js、Recharts、Redis（Upstash + ioredis）、Zod、simple-statistics、HuggingFace Transformers（小規模モデル）、Google Gemini AI、nostr-tools。

インテリジェンス層

17 個の統計アナライザーが連邦政府のデータ領域を相互参照します。

アナライザー	算出内容
財務と管轄の重複	議員の献金者の業界と、その議員が所属する委員会の管轄との重複度
投票と財務の一致	議員が上位献金者のセクターに関する法案に投じた票の割合
党派との一致	実際の記名投票において、議員が党の多数派と同じ票を投じる頻度
投票の時系列変化	四半期ごとの党派との一致度と、委員会、献金、選挙のイベント
議院の基準値	投票数、欠席した投票、党派との一致度に関する議院および政党の中央値（同僚議員の基準値）
ロビー活動の経路	委員会を対象としたロビー活動の届出を、問題ごとに分類し、法案と照合
PAC から投票への追跡	PAC の献金先と、PAC の問題領域に関する法案での投票内容
株式取引と委員会の重複	議員の委員会が監督するセクターにおける STOCK Act に基づく取引
株式取引ランキング	取引件数、取引額、または遅延届出に基づく議員のランキング
セクターランキング	ある献金者セクターの法案に対する各議員の賛成票率
影響力の連鎖	ロビー活動 → 献金 → 委員会 → 該当する法案 → 投票の経路
影響力グラフ	関連する規制、執行措置、訴訟事例を加えた影響力の連鎖
時系列の近接性	関連する投票の 90 日以内に献金が行われた場合などのタイミングパターン
法案インテリジェンス	法案の政策セクターに照らした提案者の資金源と、法案とロビー活動のテキスト類似度
執行	セクター、州、または組織別の EPA および OSHA の執行措置と CFPB への苦情
Federal Register の情報抽出	規則の前文から抽出した業界、コスト、期間
市民向け概要	代表者についての 1 ページの概要。まず統計とパターン検出を示し、次に AI による要約を提示

もう 1 つ、規制アナライザーがコード内にありますが、呼び出すものがないため一覧には記載されていません。

すべてのインサイトには、信頼度スコア（0～1）、データ基準日時、方法論の説明、および相関関係は因果関係を意味しないという免責事項が含まれます。

ML パイプライン

すべてのモデルは小型で、HuggingFace Transformers を通じてサーバー側で実行されます。CIVIQ_ML_PIPELINES=off を設定すると、これらは無効になります。

• テキスト類似度：法案とロビー活動の照合、および法案のセクター分類に all-MiniLM-L6-v2 の埋め込みを使用します
• 分類：ゼロショットの法案セクター分類に nli-deberta-v3-xsmall を使用します
• 固有表現認識：Federal Register の前文からエンティティを抽出するために distilbert-NER（ONNX）を使用します
• 影響力クラスター：オフラインでの Python 計算（scripts/compute-influence-clusters.py）を JSON として提供します

オープンソースパッケージ

3 つのパッケージを独立した npm ワークスペースパッケージとして切り出しています。

• @civiq/sdk — 9 つのリソースにわたる 33 個の型付きメソッド、エラー階層、カスタム fetch の注入機能を備えた TypeScript API クライアント
• @civiq/civic-statistics — 信頼度スコアリング、同僚との比較、相関（Spearman/Pearson）、異常検知、サンプルサイズの適用
• @civiq/entity-resolution — 委員会の別名解決、ティッカーから業界へのマッピング、FEC 献金先の重複排除

コマンド

npm run dev            # Dev server at localhost:3000
npm run build          # Production build
npm run lint           # ESLint
npm run type-check     # TypeScript strict check
npm test               # Run all tests (Jest)
npm run test:e2e       # Playwright end-to-end tests
npm run validate:all   # lint + type-check + test + build
npm run diagnose:apis  # Test API connectivity

パフォーマンスのベンチマーク、データ／ML 処理、セキュリティスキャン用の追加スクリプトは、package.json で定義されています。

コントリビューション

CONTRIBUTING.md をご覧ください。

ライセンス

Apache License 2.0。Copyright 2019-2026 Mark Sandford.

自由に使用、変更、配布できます。Apache 2.0 第4条に従い、著作権表示、ライセンス、NOTICE ファイルを含めてください。クレジットの表記は歓迎しますが、必須ではありません：「CIV.IQ を使用しています。」API が提供する政府データはパブリックドメインです。@civiq/* npm パッケージは MIT ライセンスです。CIV.IQ の名称とロゴは商標であり、使用には書面による許可が必要です。LICENSE と NOTICE をご覧ください。

---

Mark Sandford - [email protected]