Build Status

A Python client for the Open States API.

The Open States project provides data on legislators, bills, committees, and districts in legislatures of all 50 US states, plus D.C. and Puerto Rico. This data is gathered directly from the legislatures, and converted to a common format for interested developers, through a JSON API and data dumps. The project was originally created by the Sunlight Foundation as a part of Sunlight Labs. The Sunlight Foundation has since shut down Sunlight Labs, and Open States is now an independent project.

This module is intended to be a replacement for the openstates methods provided by the original sunlight package. However, it is not a drop-in replacement; the methods are slightly different, and some features have been added.

Please consider donating or volunteering to support the Open States project. The data provided to the public by various legislatures can frequently change format. Without regularly-maintained scrapers and server infrastructure, this consistent and free API would not be possible.


  • Compatible with Python 2.7-3+
  • Full Unicode support
  • Supports all methods, options, and data types provided by the API
  • Methods for downloading data dumps
  • Automatic conversion of string dates and timestamps to datetime objects
  • Tested releases


pyopenstates can be installed using pip. Installation in a virtualenv is recommended.

To install the latest release, run:

$ pip install -U pyopenstates

Or, install the latest commit from git, run:

$ pip install -U git+

API Keys

To use the Open States API you must obtain an API Key.

Once you have your key you can use it with this library by setting the OPENSTATES_API_KEY environment variable or calling pyopenstates.set_api_key().


Indices and tables