Tools

10 tools covering the full Open States v3 API surface — bills, legislators, committees, events, and jurisdictions:

openstates_search_bills

Search state legislative bills with rich filtering and inline related data.

• Full-text search across bill titles, abstracts, and text (q)
• Either jurisdiction or q is required by the input schema — a call carrying neither fails schema validation, and pairing them is the reliable form, since a q-only search spans all 56 jurisdictions and times out upstream for a common term
• Filter by jurisdiction (state name, two-letter abbreviation, or OCD-ID), session, chamber, classification, subject tags, and sponsor
• Sort by latest action, first action, or update time — use sort=latest_action_desc for bills currently moving through the legislature
• include parameter requests sponsorships, actions, votes, abstracts, versions, and related bills inline — eliminates follow-up openstates_get_bill calls for most research workflows
• Sponsors carry linked person records (OCD person ID + name) when available, so a sponsor chains onward by ID rather than by name match
• Every result carries openstates_url (citable page) and updated_at (the field the default sort=updated_desc orders by)
• action_since, updated_since, and created_since date filters for change-tracking
• Pagination up to 20 results per page
• Empty-result recovery: appliedFilters echoes every filter the query was issued with and the notice names each one that narrowed it, so a zero-result answer identifies its own cause. A jurisdiction that matches no covered jurisdiction is called out by name — Open States answers an unrecognized one with zero bills rather than an error

openstates_get_bill

Fetch complete bill detail by OCD ID or path lookup.

• Two lookup modes: openstates_id (OCD bill ID from search results, preferred) or the three-part path jurisdiction + session + bill_id
• Accepts bill identifiers in legislature format (e.g., HB 1000, SB 42)
• include=votes returns full vote tallies and per-legislator positions
• include=versions,documents provides links to bill text and fiscal notes
• Sponsors carry linked person records (OCD person ID + name) when available

openstates_search_people

Search legislators and officials within one jurisdiction by name, chamber, or district, or fetch specific people by OCD person ID.

• Either jurisdiction or id is required by the input schema — a search spanning all 56 jurisdictions exceeds the upstream timeout, name-only searches included, so a call carrying neither fails schema validation. Use openstates_list_jurisdictions to pick a jurisdiction, or openstates_get_legislators_by_location when you have coordinates but no state
• id takes OCD person IDs and returns exactly those people, so it needs no jurisdiction alongside it. It resolves the IDs that search results, openstates_get_bill sponsorships, and openstates_get_committee memberships hand back — several in one call, since upstream /people accepts id repeatedly and offers no per-person detail route
• Case-insensitive substring matching on name
• org_classification targets a role type: upper (Senate), lower (House/Assembly), executive (governors and executive officials), legislature (every legislator — both chambers merged into one paginated set, all upper members then all lower)
• Omitting org_classification is not equivalent to legislature — it returns every officeholder, executive officials included
• include=offices returns phone, fax, and mailing address
• include=links returns website and social media links
• Every result carries the member's official headshot URL (image) when published, and the OCD division their district maps to (current_role.division_id)

openstates_get_legislators_by_location

Find every legislator representing a geographic coordinate, across both tiers of government.

• Pass decimal-degree latitude/longitude to get the state senators and representatives for that location, plus its two US Senators and its US Representative
• jurisdiction.classification separates the tiers: "state" is a state legislature, "country" is the US Congress. current_role.org_classification does not — it is upper/lower for a US Senator exactly as for a state senator
• stateCount and federalCount report the split, and the rendered text labels each legislator's tier
• Useful for constituent-to-representative matching, address-based policy research, and electoral boundary analysis
• Does not geocode addresses — the caller must provide coordinates
• Returns a coverage note when no legislators are found (e.g., coordinates outside US boundaries)

openstates_list_jurisdictions and openstates_get_jurisdiction

Discover and look up jurisdiction coverage metadata.

• openstates_list_jurisdictions returns all 56 jurisdictions (50 states, DC, and 5 US territories) in a single default call — the pages are merged server-side, since the upstream per_page ceiling of 52 no longer covers the full set
• include=legislative_sessions returns all historical and current session identifiers — required before filtering bill searches by session, since formats vary widely by state (e.g., 2025, 2025-2026, 2025rs, 2025s1)
• openstates_get_jurisdiction fetches one jurisdiction by OCD-ID, state name, or two-letter abbreviation

Committee and event tools (experimental)