A Node.js + Fastify service that transforms official House, Senate, and Congress.gov data into a single, cache-friendly API. Designed to power the Civic Duty mobile app with timely legislative intelligence, ready-made digests, and civic trend insights.
The Civic Duty app helps constituents stay informed without wrestling with raw XML or multiple upstream feeds. This backend normalizes roll-call votes, floor schedules, hearing calendars, and trending bills, then layers on scoring, heuristics, and (optional) AI narratives. Every route is built to be respectful of Clerk.house.gov and Congress.gov rate limits while giving mobile clients the concise, contextual data they need.
Use the routes below to drive personalized weekly digests, surface the most-viewed legislation, or embed transparent vote explanations in your own tools.
Builds a personalized weekly or monthly briefing with 10 ranked highlights, rep vote cards (with party labels), committee actions, CRS reports, and optional Gemini summaries. Accepts user preferences and localization tweaks.
curl "http://localhost:8080/digest?weekOf=2025-03-03&language=en"One-stop bundle for the app home screen: digest highlights, recent House/Senate votes, floor schedule, most viewed bills, and tracked rep vote summaries, all cache-friendly and Firestore-aware.
curl "http://localhost:8080/dashboard?language=en"
Aggregates roll-call votes from the House Clerk and Senate.gov with unified pagination, directory enrichment,
Firestore lookups, and a live=true flag for fresh source pulls.
curl "http://localhost:8080/votes?year=2025&chamber=house&page=1"Blends Congress.gov "most viewed" bills with Google Trends questions to show what the public is searching. Can optionally layer AI summaries when Gemini access is enabled.
curl "http://localhost:8080/public/pulse"Congress.gov member directory with filters for state, chamber, district, and Congress session. Enriches downstream screens with imagery and contact details.
curl "http://localhost:8080/member?state=NY&chamber=house"Every route returns JSON with a meta block describing upstream sources, caching hints, and pagination. Unless otherwise noted, query parameters are optional and support pagination through page and perPage.
| Method | Path | Purpose |
|---|---|---|
| GET | /healthz | Service heartbeat with uptime and timestamp. |
| GET | /votes | House and Senate roll call listings (filters: year, chamber, page, perPage). |
| GET | /votes/{year}/{roll} | Single roll call detail with totals, bill metadata, and directory-enriched positions (supports live=true). |
| GET | /votes/{year}/{roll}/members | Roll call detail plus vote positions for each member. |
| GET | /public/pulse | Most viewed bills with related Google Trends topics and optional AI summaries. |
| GET | /digest | Weekly or monthly personalized digest with highlights, AI summaries, and rep vote breakdowns. |
| GET | /dashboard | Combined highlights, recent votes, schedule, and trends for the app landing page (tunable limits). |
| GET | /member | Member directory filtered by state, chamber, district, Congress, pagination. |
| GET | /member/{bioguideId} | Member profile with biography, committees, and social links when available. |
| GET | /member/{bioguideId}/sponsored-legislation | Sponsored legislation list for a member. |
| GET | /member/{bioguideId}/cosponsored-legislation | Cosponsored legislation list for a member. |
| GET | /member/congress/{congress} | Directory filtered by Congress session. |
| GET | /member/congress/{congress}/{stateCode} | Directory filtered by Congress session and state. |
| GET | /member/congress/{congress}/{stateCode}/{district} | Directory filtered by Congress session, state, and district. |
| GET | /member/{stateCode}/{district} | Current Congress directory for a specific state and district. |
| GET | /bill | Latest Congress.gov bills listing (filters: congress, billType, page, perPage). |
| GET | /bill/{congress} | Congress specific bill listing (filters: billType, page, perPage). |
| GET | /bill/{congress}/{billType} | Bill listing filtered by Congress and type. |
| GET | /bill/{congress}/{billType}/{billNumber} | Detailed bill metadata with actions and latest status. |
| GET | /bill/{congress}/{billType}/{billNumber}/actions | Paged history of actions for a bill. |
| GET | /law/{congress} | List of public and private laws for a Congress session. |
| GET | /law/{congress}/{lawType} | Law listing filtered by type (public or private). |
| GET | /law/{congress}/{lawType}/{lawNumber} | Detailed law entry with related bill metadata. |
| GET | /members/{bioguideId}/profile | Member profile sourced from Clerk (House) or Congress.gov (Senate). |
| GET | /members/{bioguideId}/recent-votes | Recent roll call votes for a House member (Senate returns HTTP 501). |
| GET | /bills | Paginated Congress.gov bill list mirroring the public site sort order. |
| GET | /bills-this-week | Docs.house.gov floor schedule; supply date=YYYYMMDD to set the calendar week. |
Shortened example showing the structure mobile clients receive. Counts summarize weekly activity; items are scored events tailored to the user; downstream sections cover hearings, committee work, and reports.
{
"summary": {
"headline": "Weekly outlook for Mar 3 - Mar 9",
"counts": {
"billsIntroduced": 6,
"votesHeld": 5,
"hearings": 2
}
},
"items": [
{
"type": "bill",
"title": "Education Funding Stabilization Act",
"why": "You follow this bill.",
"links": {
"inApp": "/bill/119/hr123",
"source": "https://www.congress.gov/bill/119th-congress/house-bill/123"
}
}
],
"repVotes": [
{
"name": "Rep. Alex Adams",
"aiSummary": {
"text": "Rep. Alex Adams cast 1 yea this week."
}
}
]
}
Boot the service locally with npm run dev and explore routes using the examples above. Environment
variables such as CONGRESS_API_KEY, PUBLIC_PULSE_USE_MOCKS, and
ENABLE_GEMINI_DIGEST let you control upstream access, caching windows, and optional AI
enhancements.
Production deployments typically front this service with an API gateway or CDN. Each response includes a
meta block describing upstream sources and cache hints so clients can show provenance alongside
the data.
All outbound calls share a custom user agent, concurrency guardrails, and backoff strategy to stay within Congress.gov and Clerk.house.gov guidelines. Cached windows (5-30 minutes for listings, 24 hours for detailed votes) keep traffic predictable while ensuring Civic Duty users see fresh updates quickly.
Want to contribute improvements or new routes? Check the project roadmap in the repository and open a pull request; this service is built to grow alongside Civic Duty's civic engagement mission.