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

Parameters:	state – The abbreviation of the state file_object – A file or file-like object data_format – `json` or `csv`

Note

json format provides much more detail than csv.

Examples

# Saving Ohio's data to a file on disk
with open("ohio-json.zip", "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

Parameters:	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) –
Returns:	The Bill details as a dictionary

pyopenstates.get_committee(com_id, fields=None)¶

Gets committee details

Parameters:	com_id – Open States committee ID fields – An optional, custom set of fields to return
Returns:	The requested Committee details as a dictionary

pyopenstates.get_district(boundary_id, fields=None)¶

Gets district details

Parameters:	boundary_id – The boundary ID fields – Optionally specify a custom list of fields to return
Returns:	The requested District details as a dictionary

pyopenstates.get_event(event_id, fields=None)¶

Gets event details

Parameters:	event_id – The Open States Event UUID fields – An optional list of fields to return
Returns:	The requested Event details as a dictionary

pyopenstates.get_legislator(leg_id, fields=None)¶

Gets a legislator’s details

Parameters:	leg_id – The Legislator’s Open States ID fields – An optional custom list of fields to return
Returns:	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.

Parameters:	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
Returns:	The requested Metadata as a dictionary
Return type:	Dict

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

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

Parameters:	lat – Latitude long – Longitude fields – An optional custom list of fields to return
Returns:	A list of matching Legislator dictionaries

pyopenstates.search_bills(**kwargs)¶

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

Note

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.

pyopenstates.search_committees(**kwargs)¶

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

Parameters:	state – The state to search in chamber – the upper or lower legislative chamber fields – Optionally specify a custom list of fields to return
Returns:	A list of matching District dictionaries

pyopenstates.search_events(**kwargs)¶

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

pyopenstates.search_legislators(**kwargs)¶

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

pyopenstates.set_api_key(apikey)¶: Sets API key. Can also be set as OPENSTATES_API_KEY environment variable.

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