Open States API v1¶
An alpha of API v2 is now available, please check out API v2.
Open States provides a JSON API for accessing state legislative information.
- All API calls are URLs in the form
- Responses are JSON unless otherwise specified.
- If an error occurs the response will be a plain text error message with an appropriate HTTP error code (404 if object is not found, 401 if authentication fails, etc.).
- To use the API you must register for an API key.
- Once activated, pass your API key via the
apikeyquery paramter or the
- All changes to the API will be announced on the Open States Discourse. It is recommended you subscribe if you’re using the API.
- For Python users, there’s an official pyopenstates package available.
Open States provides data about six core data types.
- State Metadata
- Details on what data is available, including terms, sessions, and state-specific names for things.
- Details on bills & resolutions, including actions & votes.
- Details on legislators, including contact details.
- Details on districts and their boundaries.
- Committees endpoints have been deprecated and will no longer return current data as of October 2018.
- Events endpoints have been deprecated and will no longer return current data as of 2018.
|Metadata Overview||/metadata/||Get list of all states with data available and basic metadata about their status.|
|State Metadata||/metadata/state/||Get detailed metadata for a particular state.|
|Bill Search||/bills/||Search bills by (almost) any of their attributes, or full text.|
|Bill Detail||/bills/state/session/bill_id/||Get full detail for bill, including any actions, votes, etc.|
|Legislator Search||/legislators/||Search legislators by their attributes.|
|Legislator Detail||/legislators/leg_id/||Get full detail for a legislator, including all roles.|
|Geo Lookup||/legislators/geo/?lat=latitude&long=longitude||Lookup all legislators that serve districts containing a given point.|
|District Search||/districts/state/[chamber/]||List districts for state (and optionally filtered by chamber).|
|District Boundary Lookup||/districts/boundary/boundary_id/||Get geographic boundary for a district.|
Requesting A Custom Fieldset¶
On essentially every method in the API it is possible to specify a
custom subset of fields on an object by specifying a
There are two use cases that this functionality aims to serve:
First, if you are writing an application that loads a lot of data but only uses some of it, specifying a limited subset of fields can reduce response time and bandwidth. We’ve seen this approach be particuarly useful for mobile applications where bandwidth is at a premium.
An example would be a legislator search with
fields=first_name,last_name,leg_id specified. All legislator objects
returned will only have the three fields that you requested.
Second, you can actually specify a set of fields that includes fields excluded in the default response.
For instance, if you are conducting a bill search, it typically does not include sponsors, though many sites may wish to use sponsor information without making a request for the full bill (which is typically much larger as it includes versions, votes, actions, etc.).
A bill search that specifies
will include the full sponsor listing in addition to the standard
bill_id, title and chamber fields.
You may notice that the fields documented are sometimes a subset of the fields actually included in a response.
Many times as part of our scraping process we take in data that is available for a given state and is either not available or does not have an analog in other states. Instead of artificially limiting the data we provide to the smallest common subset we make this extra data available.
To make it clear which fields can be relied upon and which are perhaps
specific to a state or subset of states we prefix non-standard fields
If you are using the API to get data for multiple states, it is best to restrict your usage to the fields documented here. If you are only interested in data for a small subset of our available states it might make sense to take a more in depth look at the API responses for the state in question to see what extra data we are able to provide.