congressgov 2.0.0

Python SDK for the Congress.gov API — services, models, and generated HTTP client

congressgov

Python SDK for the Congress.gov API — typed Pydantic models, high-level services, and query extensions.

Community client for the official Congress.gov API specification (not affiliated with the Library of Congress). PyPI package: congressgov · This repo: congressgov-python

Features

• Typed models — Pydantic validation for bills, members, committees, and more
• High-level services — Bill, Member, Committee, and 15+ other resource classes
• Query extensions — get_actions(), filter(), group_by(), and chainable queries on collections
• Async — parallel AsyncBill, AsyncMember, … under congressgov.async_api

Requirements

• Python 3.13+
• A free Congress.gov API key

Installation

Requires 2.0.0 or newer for the current src/ layout without legacy shims. Use 1.5.x if you still need import middleware / import models; 1.0.0 did not ship a congressgov module at all.

pip install "congressgov>=2.0.0"

Full install (all optional runtime features):

pip install congressgov[all]

From source (development):

git clone https://github.com/CMD0112/congressgov-python.git
cd congressgov-python
poetry install --with dev,cache,export,batch,codegen
# Or: pip install -e ".[dev,all,codegen]"

First-time maintainers wiring a new GitHub remote: docs/GITHUB_SETUP.md.

API key

cp .env.example .env
# Set CONGRESS_API_KEY=your-key-here

Or export CONGRESS_API_KEY in your shell. The library reads it via get_client_from_env().

Quick start

from congressgov import Bill, get_client_from_env

client = get_client_from_env()
bill = Bill(client=client).get(congress=118, bill_type="hr", bill_number=1)

print(bill.title)
print(len(bill.get_actions() or []), "actions")

Run the sample scripts (with CONGRESS_API_KEY set):

poetry run python examples/quickstart.py
poetry run python examples/quickstart_async.py

Async

from congressgov.async_api import AsyncBill

bill = await AsyncBill(client=client).get(
    congress=118, bill_type="hr", bill_number=1
)

Architecture

flowchart TB
  subgraph app [Your application]
    UserCode[Your code]
  end
  subgraph sdk [congressgov SDK]
    Facade[congressgov facade]
    SVC[services]
    MD[models]
    CL[congressgov._client]
  end
  API[Congress.gov API v3]
  UserCode --> Facade
  Facade --> SVC
  SVC --> MD
  SVC --> CL
  CL --> API

Layer	Import	Role
Facade	congressgov	Canonical public API (Bill, Member, …)
Services	congressgov.services	High-level API services
Models	congressgov.models	Parsed, validated data
Client	congressgov.client or congressgov._client	Generated HTTP calls

Optional features

Caching, batch jobs, export, and rate limiting require optional extras (lazy-imported from congressgov):

Extra	Install	Enables
cache	pip install congressgov[cache]	CachedBill, RedisCache, RateLimiter, …
export	pip install congressgov[export]	DataExporter, PandasIntegration, …
batch	pip install congressgov[batch]	BatchProcessor, …
all	pip install congressgov[all]	All of the above
codegen	pip install congressgov[codegen]	Maintainer deps only; run python -m codegen from a git clone
viz	pip install congressgov[viz]	Matplotlib helpers in export visualization

Details: docs/ADVANCED.md. Architecture: docs/ARCHITECTURE.md.

Regenerating from OpenAPI

The committed client and models are generated from codegen/config/openapi_spec.yaml. To regenerate after spec changes:

poetry install --with codegen
poetry run python -m codegen validate-spec
poetry run python -m codegen generate-all

Stepwise: python -m codegen generate-client, generate-models, generate-middleware.

• Spec: codegen/config/openapi_spec.yaml
• Config: codegen/config/generator_config.yaml
• Incremental mode preserves # CUSTOM: blocks in generated files
• Do not overwrite hand-maintained middleware/async_api/bill.py and cached_bill.py

Full workflow: docs/CODEGEN.md

Documentation

Guide	Contents
docs/USAGE.md	Getting started, async, errors, congressional record types
docs/PACKAGE_LAYOUT.md	Directory layout, wheel policy, 2.0 src/ plan
docs/MIGRATION.md	Import path changes (1.1 → 2.0)
docs/VERSIONING.md	SemVer, deprecations, stability scope
docs/REFERENCE.md	Services, client, models, extensions
docs/ADVANCED.md	Caching, batch, export, rate limits
docs/ARCHITECTURE.md	Core vs extras, generated vs hand-maintained
docs/CODEGEN.md	OpenAPI code generation (maintainers)
docs/PUBLISHING.md	PyPI trusted publishing (maintainers)
docs/API_COVERAGE.md	OpenAPI path coverage matrix (maintainers)

Contributing

See CONTRIBUTING.md. Security: SECURITY.md. Releases: CHANGELOG.md.

License

Apache-2.0