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
orcsv
Note
json
format provides much more detail thancsv
.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
orlower
) -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 tosearch_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 named2009
. -search_window="term:2009-2011"
- Only bills from the sessions in the2009-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 abbreviationReturns: 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
orformat=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
)