Open States v3 API¶
Open States provides a JSON API that can be used to programatically access state legislative information.
API Basics¶
The root URL for the API is https://v3.openstates.org/.
API keys are required. You can register for an API key and once activated, you’ll pass your API key via the X-API-KEY header or ?apikey query parameter.
Auto-generated interactive documentation is available at either:
- https://v3.openstates.org/docs/
- https://v3.openstates.org/redoc/ (whichever you prefer)
Issues should be filed at our issue tracker.
You can also check out our introductory blog post for more details.
Methods¶
| Method | Description | Interactive Docs |
|---|---|---|
| /jurisdictions | Get list of available jurisdictions. | [1] |
| /jurisdictions/{jurisdiction_id} | Get detailed metadata for a particular jurisdiction. | [2] |
| /people | List or search people (legislators, governors, etc.) | [3] |
| /people.geo | Get legislators for a given location. | [4] |
| /bills | Search bills by various criteria. | [5] |
| /bills/ocd-bill/{uuid} | Get bill by internal ID. | [6] |
| /bills/{jurisdiction}/{session}/{id} | Get bill by jurisdiction, session, and ID. | [7] |
Concepts¶
- Jurisdiction
- The fundamental unit by which data is partitioned is the ‘jurisdiction.’ If you are just interested in states you can consider the words synonymous for the most part. Jurisdictions include states, DC & Puerto Rico, and municipal governments for which we have limited support.
- Person
A legislator, governor, mayor, etc.
Each person possibly has a number of roles, at most one of which is considered ‘current.’
- Bill
A proposed piece of legislation, encompasses bills, resolutions, constitutional amendments, etc.
A given bill may have any number of votes, sponsorships, actions, etc.