civiq

CIV.IQ

来自政府来源的公民信息，整理后供公众使用。

civdotiq.org • API 参考 • 参与贡献 • 许可证

---

项目简介

一个公民信息平台。输入地址，即可查找您的联邦和州级代表，并查看他们的投票记录、联邦竞选财务、委员会任职情况、立法活动，以及由机器学习驱动的政治金钱模式分析。本平台不涵盖市、县等地方政府。地方记录缺乏统一标准或中央来源；CIV.IQ 计划仅在存在经过核实的公共来源后才纳入这些记录。

数据来自官方政府记录。大多数数据直接通过政府机构的 API 或批量文件读取；部分数据通过具名开放数据集读取，例如州议会数据来自 OpenStates，解析后的《股票法案》申报数据来自 Congress Trading Monitor。所有分析均为统计分析，并公开置信度评分和方法。如果数据不可用，界面和响应内容会明确说明。绝不捏造数据。

如实呈现的覆盖范围矩阵：docs/COVERAGE.md。这是关于“CIV.IQ 实际涵盖什么？”的权威说明；本 README 中的其他所有说法均以该页面为准。

功能

代表：联邦和州立法者，包含照片、联系信息、委员会任职情况和投票记录。

竞选财务：仅限联邦层面——FEC 捐款、PAC 支出、支出追踪和捐赠者行业分析。目前不提供州级竞选财务信息（FollowTheMoney.org 在 OpenSecrets 合并期间处于维护模式）。

情报层：统计分析器会交叉参照投票记录、竞选财务、游说申报、股票交易和委员会管辖范围，以揭示可能存在影响力的模式。每条洞察都附有置信度评分、方法说明，以及相关性不代表因果关系的免责声明。

资金报告：基于地址的查询，可追踪从竞选捐款、委员会任职到特定代表立法结果的资金流向。

法规与意见征集期：集成 Federal Register，涵盖拟议规则、最终规则、行政命令和开放的公众意见征集期。

州立法机构：通过 OpenStates 覆盖全部 50 个州，包括立法者、法案、委员会和日程。按立法者查询投票历史的功能正在开发中。为全部 7,383 个州立法选区提供交互式选区边界地图。州级竞选财务、游说和股票交易数据不属于州级覆盖范围。

地方政府：暂不覆盖（城市／县）。地方记录缺少通用标准或中央数据源；CIV.IQ 计划仅在存在经过验证的公共数据源后才添加相关内容。

选区情报：人口统计、经济指标（BLS 就业数据）、联邦支出（USASpending）、基础设施指标，以及按与各国会选区相关性排序的法案。

Nostr 发布：公民事件（新法案、投票、听证会）经过签名后发布到 Nostr 网络，以实现去中心化、可验证的分发。

开发者集成

集成	提供内容
OpenAPI 规范	39 个端点、38 个架构——可使用任何语言生成客户端
@civiq/sdk	零依赖 TypeScript 客户端（npm install @civiq/sdk）
MCP 服务	为 AI 助手（Claude、Cursor 等）提供 46 个工具
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 Act 进行的交易，解析自众议院和参议院官方申报
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

将 API 密钥添加到 .env.local。这些密钥均可免费获取：

# 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

完整列表见 .env.example，其中还包括 Nostr 发布和 ActivityPub 联邦功能所需的密钥。

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（严格模式）、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 法案》交易
股票交易排行榜	按交易次数、交易金额或延迟申报情况对成员排名
行业排行榜	每位成员在某一捐款人所属行业相关法案上的赞成票比例
影响链	游说 → 捐款 → 委员会 → 匹配法案 → 投票的路径
影响关系图	在影响链基础上扩展相关法规、执法行动和法院案件
时间邻近性	时间模式，例如在相关投票前 90 天内收到捐款
法案智能分析	提案人的资金来源与法案政策领域的对照，以及法案文本与游说文本的相似度
执法	按行业、州或组织统计 EPA 和 OSHA 的执法行动以及 CFPB 的投诉
《联邦公报》信息提取	从规则序言中提取行业、成本和时间线
公民简报	一页式代表简报：优先呈现统计数据和模式检测结果，然后提供 AI 摘要

代码中还有一个法规分析器，但未列出，因为没有任何地方调用它。

每条洞察均包含：置信度评分（0–1）、数据截至时间戳、方法说明，以及相关性不代表因果关系的免责声明。

ML 流水线

所有模型都体量较小，并通过 HuggingFace Transformers 在服务器端运行。将 CIVIQ_ML_PIPELINES=off 设为关闭状态即可禁用这些模型。

• 文本相似度：使用 all-MiniLM-L6-v2 嵌入来匹配法案与游说内容，并对法案进行行业分类
• 分类：使用 nli-deberta-v3-xsmall 进行零样本法案行业分类
• 命名实体识别：使用 distilbert-NER（ONNX）从《联邦公报》序言中提取实体
• 影响力集群：通过离线 Python 计算（scripts/compute-influence-clusters.py），并以 JSON 格式提供

开源软件包

三个软件包被提取为独立的 npm 工作区软件包：

• @civiq/sdk — TypeScript API 客户端，涵盖 9 种资源的 33 个类型化方法，并提供错误层级结构和自定义 fetch 注入
• @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

package.json 中定义了用于性能基准测试、数据/机器学习处理和安全扫描的其他脚本。

贡献

请参阅 CONTRIBUTING.md。

许可证

Apache License 2.0。版权所有 2019-2026 Mark Sandford。

可使用、修改和分发。请根据 Apache 2.0 第 4 条，附上版权声明、许可证和 NOTICE 文件。欢迎署名，但并非必须：“Powered by CIV.IQ.” API 提供的政府数据属于公有领域。@civiq/* npm 包采用 MIT 许可证。CIV.IQ 名称和徽标是商标，使用前须获得书面许可。请参阅 LICENSE 和 NOTICE。

---

Mark Sandford - [email protected]