Skip to content

API v3 Overview

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:

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. try it!
/jurisdictions/{jurisdiction_id} Get detailed metadata for a particular jurisdiction. try it!
/people List or search people (legislators, governors, etc.) try it!
/people.geo Get legislators for a given location. try it!
/bills Search bills by various criteria. try it!
/bills/ocd-bill/{uuid} Get bill by internal ID. try it!
/bills/{jurisdiction}/{session}/{id} Get bill by jurisdiction, session, and ID. try it!
/committees Get list of committees by jurisdiction. try it!
/committees/{committee_id} Get details on committee by internal ID. try it!
/events Get list of events by jurisdiction. try it!
/events/{event_id} Get details on event by internal ID. try it!

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.