pyopenstates module

A Python client for the Open States API

exception pyopenstates.APIError

Raised when the Open States API returns an error

exception pyopenstates.NotFound

Raised when the API cannot find the requested object

pyopenstates.download_bulk_data(state, file_object, data_format='json')

Downloads a zip containing bulk data on a given state to a given file object

  • state – The abbreviation of the state
  • file_object – A file or file-like object
  • data_formatjson or csv


json format provides much more detail than csv.


# Saving Ohio's data to a file on disk
with open("", "wb") as ohio_zip_file:
    pyopenstates.bulk_download("OH", ohio_zip_file)

# Or download it to memory
from io import BytesIO
mem_zip = BytesIO()
pyopenstates.bulk_download("OH", mem_zip)
pyopenstates.get_bill(uid=None, state=None, term=None, bill_id=None, **kwargs)

Returns details of a specific bill Can be identified my the Open States unique bill id (uid), or by specifying the state, term, and legislative bill ID

  • uid – The Open States unique bill ID
  • state – The postal code of the state
  • term – The legislative term (see state metadata)
  • bill_id – Yhe legislative bill ID (e.g. HR 42)
  • **kwargs – Optional keyword argument options, such as fields,
  • specifies the fields to return (which) –

The Bill details as a dictionary

pyopenstates.get_committee(com_id, fields=None)

Gets committee details

  • com_id – Open States committee ID
  • fields – An optional, custom set of fields to return

The requested Committee details as a dictionary

pyopenstates.get_district(boundary_id, fields=None)

Gets district details

  • boundary_id – The boundary ID
  • fields – Optionally specify a custom list of fields to return

The requested District details as a dictionary

pyopenstates.get_event(event_id, fields=None)

Gets event details

  • event_id – The Open States Event UUID
  • fields – An optional list of fields to return

The requested Event details as a dictionary

pyopenstates.get_legislator(leg_id, fields=None)

Gets a legislator’s details

  • leg_id – The Legislator’s Open States ID
  • fields – An optional custom list of fields to return

The requested Legislator details as a dictionary

pyopenstates.get_metadata(state=None, fields=None)
Returns a list of all states with data available, and basic metadata about their status. Can also get detailed metadata for a particular state.
  • state – The abbreviation of state to get detailed metadata on, or leave
  • None to get high-level metadata on all states. (as) –
  • fields – An optional list of fields to return; returns all fields by default

The requested Metadata as a dictionary

Return type:


pyopenstates.locate_legislators(lat, long, fields=None)

Returns a list of legislators for the given latitude/longitude coordinates

  • lat – Latitude
  • long – Longitude
  • fields – An optional custom list of fields to return

A list of matching Legislator dictionaries


Find bills matching a given set of filters

Parameters:**kwargs – One or more search filters
  • state - Only return bills from a given state (e.g. nc)
  • chamber - Only return bills matching the provided chamber

(upper or lower) - bill_id - Only return bills with a given bill_id. - bill_id_in - Accepts a pipe (|) delimited list of bill ids. - q - Only return bills matching the provided full text query. - search_window- By default all bills are searched, but if a time window is desired the following options can be passed to search_window:

  • search_window="all" - Default, include all sessions.
  • search_window="term" - Only bills from sessions within the

current term. - search_window="session" - Only bills from the current session. - search_window="session:2009" - Only bills from the session named 2009. - search_window="term:2009-2011" - Only bills from the sessions in the 2009-2011 session.

  • updated_since - Only bills updated since a provided date (provided in

YYYY-MM-DD format) - sponsor_id Only bills sponsored by a given legislator id (e.g. ILL000555) - subject - Only bills categorized by Open States as belonging to this subject. - type Only bills of a given type (e.g. bill, resolution, etc.)

You can specify sorting using the following sort keyword argument values:

  • first
  • last
  • signed
  • passed_lower
  • passed_upper
  • updated_at
  • created_at
Returns:A list of matching Bill dictionaries


This method returns just a subset (state, chamber, session, subjects, type, id, bill_id, title, created_at, updated_at) of the bill fields by default.

Use the fields parameter to specify a custom list of fields to return.


Search for and return a list of matching committees

Parameters:**kwargs – One or more filter keyword arguments
  • committee - Name of committee.
  • subcommittee - Name of subcommittee. (if None, object describes the

committee) - chamber - Chamber committee belongs to: upper, lower, or ` joint` - state - State abbreviation

Returns:A list of matching Committee dictionaries
pyopenstates.search_districts(state, chamber, fields=None)

Search for districts

  • state – The state to search in
  • chamber – the upper or lower legislative chamber
  • fields – Optionally specify a custom list of fields to return

A list of matching District dictionaries


Searches events

Events are not available in all states, to ensure that events are available check the feature_flags list in a states’ State Metadata.

Parameters:**kwargs – One or more search filters
  • state - State abbreviation.
  • type - Categorized event type. (committee:meeting for now)

This method also allows specifying an alternate output format, by specifying format=rss or format=ics.

Returns:A list of matching Event dictionaries

Search for legislators

Parameters:**kwargs – One or more search filters
  • state - Filter by state.
  • first_name - Filter by first name.
  • last_name - Filter by last name.
  • chamber - Only legislators with a role in the specified chamber.
  • active - True (default) to only include current legislators,

False will include all legislators - term - Only legislators that have a role in a certain term. - district - Only legislators that have represented the specified district. - party - Only legislators that have been associated with a specified party.

Returns:A list of matching Legislator dictionaries

Sets API key. Can also be set as OPENSTATES_API_KEY environment variable.


Appends a custom string to the default User-Agent string (e.g. pyopenstates/__version__ user_agent)