Open States v3 API

Open States provides a JSON API that can be used to programatically access state legislative information.

Note

API v3 is in beta as of September 2020. We are expecting to make a few changes, some of which might introduce small backwards incompatible changes. While we encourage you to use the API, please be prepared to keep up to date at least through December 2020 when we expect the API will be officially designated as stable.

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:

Issues should be filed at our issue tracker.

You can also check out our introductory blog post for more details.

Note

API Limits are not yet defined or enforced, we’re currently evaluating different tiers, but we aim to support 80% of users in our free tier. If you’re curious about your particular use case please reach out to contact@openstates.org.

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.