Documentation

A module for iterating though results from the FEC API.

This module provides several useful utilities for iterating through paginated results from the FEC API. The meat of this module is in the filing_iterator.FilingIterator class, which encapsulates the logic of interacting with the FEC API and iterating through the returned results. In theory the FilingIterator class can iterate through the results of any endpoint that the FEC API provides.

Included are several iterator factory functions that allow you to create instances of the FilingIterator class to handle common endpoints, such as those for Schedule A filings. In many cases one of the factory functions will allow you easy access to the data you need, but if you want access to a specific endpoint of the API you can always create your own iterator directly.

Note

All of the factory functions and the FilingIterator class can be imported directly from the top-level of the module, so the following will both work:

>>> from fec_filing_iterator import schedules
>>> from fec_filing_iterator.factories import candidates

Iterator Factories

fec_filing_iterator.factories.candidates(**kwargs)

Iterator factory that creates an iterator to loop through candidates returned from the FEC /canidates/ endpoint. This endpoint allows you to “fetch basic information about candidates, and use parameters to filter results to the candidates you’re looking for”.

Kwargs:

All keyword arguments are forwarded to the filing_iterator.FilingIterator object

For example, you could get each candidate’s FEC candidate ID with:

>>> for cand in candidates(**kwargs):
...     print(cand['candidate_id'])

fec_filing_iterator.factories.committees(**kwargs)

Iterator factory that creates an iterator to loop through committees returned from the FEC /committees/ endpoint. This endpoint allows you to “fetch basic information about committees and filers” and “use parameters to filter for particular characteristics”.

Kwargs:

All keyword arguments are forwarded to the filing_iterator.FilingIterator object

For example, you could get each committee’s FEC ID with:

>>> for cmte in committees(**kwargs):
...     print(cmte['committee_id'])

fec_filing_iterator.factories.dates(date_type, **kwargs)

Iterator factory that creates an iterator to loop through different kinds of dates returned from the FEC API. The API has separate endpoints for calendar dates (/calendar-dates/), election dates (/election-dates/), and reporting dates (/reporting-dates/), and this interator factory supports all three. These endpoints give you access to reporting deadlines, election dates, FEC meetings and events, and more.

Args:

date_type (str): The type of dates to query (‘calendar’, ‘election’, or ‘reporting’)

Kwargs:

All keyword arguments are forwarded to the filing_iterator.FilingIterator object

For example, you could get each election date with:

>>> for elec in dates('election', **kwargs):
...     print(elec['election_date'])

fec_filing_iterator.factories.filings(**kwargs)

Iterator factory that creates an iterator to loop through all filings returned from the FEC /filings/ endpoint. This endpoint gives you access to “all official records and reports filed by or delivered to the FEC”.

For example, you could get each filing’s form type with the following (though you’ll be waiting for a very long time):

>>> for filing in filings(**kwargs):
...     print(filing['form_type'])

fec_filing_iterator.factories.schedules(schedule_type, **kwargs)

Iterator factory that creates an iterator to loop through all schedules returned from the various FEC schedules endpoints, including /schedules/schedule_a/ and /schedules/schedule_b/. The API has endpoints for schedule types A through F, and this factory supports all of them.

For example, you could get all of the disbursements made by the committee Bernie 2020 with:

>>> bernie_disbursements = []
>>> for filing in schedules('b', **kwargs):
...     bernie_disbursements.append(filing)

Filing Iterator

class fec_filing_iterator.filing_iterator.FilingIterator(*args, api_key=None, params=None, pagination=None, per_page=100, paged=False)

Main filing iterator class

This class encapsulates the logic of interacting with the FEC API and iterating through the paged results that are returned in order to present the full set of results as a single, lazily evaluated, iterable stream.

Args:

Positional arguments are combined to create a URL

Kwargs:

api_key (str): FEC API key

params (dict): Parameters to pass to the FEC API

pagination (dict): API pagination information to start your iteration from

per_page (int): Number of results to return per page, max is 100, which is also the default

paged (bool): Whether the results are paginated using normal page-based pagination or with numbered indexes. Most endpoints are normally paginated, but notably some of the schedule endpoints use indexes

Example:

>>> api_key = 'YOU_FEC_API_KEY'
>>> params = {
...     'two_year_transaction_period': [2018, 2020],
...     'committee_id': 'C00696948',
... }
>>> for schedule in FilingIterator(
...     'schedules',
...     'schedule_a',
...     api_key=api_key,
...     params=params
... ):
...     print(schedule)

Errors

exception fec_filing_iterator.errors.Error

Base error class for other more specific error classes

exception fec_filing_iterator.errors.FecApiError

Raised when there is a problem encountered with the FEC API (e.g., when an invalid request is made or when the API rate limit is exceeded after all retries are exhausted)