openfec: Index | Examples | Files

package openfec

import ""

Package openfec implements a client library for the OpenFEC API.



This package all allows you to explore the way candidates and committees fund their campaigns by accessing FEC (Federal Election Committee) data.

A few restrictions limit the way you can use FEC data. For example, you can’t use contributor lists for commercial purposes or to solicit donations.

Get an API key here:

Endpoints are classified in the following groups: Candidate, Committee, Financial, Filings and Schedules.


Candidate endpoints give you access to information about the people running for office. This information is organized by candidate_id. If you're unfamiliar with candidate IDs, using `/candidates/search` will help you locate a particular candidate.

Officially, a candidate is an individual seeking nomination for election to a federal office. People become candidates when they (or agents working on their behalf) raise contributions or make expenditures that exceed $5,000.

The candidate endpoints primarily use data from FEC registration [Form 1](, for candidate information, and [Form 2](, for committee information.


Committees are entities that spend and raise money in an election. Their characteristics and relationships with candidates can change over time.

You might want to use filters or search endpoints to find the committee you're looking for. Then you can use other committee endpoints to explore information about the committee that interests you.

Financial information is organized by `committee_id`, so finding the committee you're interested in will lead you to more granular financial information.

The committee endpoints include all FEC filers, even if they aren't registered as a committee.

Officially, committees include the committees and organizations that file with the FEC. Several different types of organizations file financial reports with the FEC:

* Campaign committees authorized by particular candidates to raise and spend funds in their campaigns * Non-party committees (e.g., PACs), some of which may be sponsored by corporations, unions, trade or membership groups, etc. * Political party committees at the national, state, and local levels * Groups and individuals making only independent expenditures * Corporations, unions, and other organizations making internal communications

The committee endpoints primarily use data from FEC registration Form 1 and Form 2.


Fetch key information about a committee's Form 3, Form 3X, or Form 3P financial reports.

Most committees are required to summarize their financial activity in each filing; those summaries are included in these files. Generally, committees file reports on a quarterly or monthly basis, but some must also submit a report 12 days before primary elections. Therefore, during the primary season, the period covered by this file may be different for different committees. These totals also incorporate any changes made by committees, if any report covering the period is amended.

Information is made available on the API as soon as it's processed. Keep in mind, complex paper filings take longer to process.

The financial endpoints use data from FEC [form 5](, for independent expenditors; or the summary and detailed summary pages of the FEC [form 3](, for House and Senate committees; [form 3X](, for PACs and parties; and [form 3P](, for presidential committees.


All official records and reports filed by or delivered to the FEC.

Note: because the filings data includes many records, counts for large result sets are approximate.


Schedules come from particular sections on forms and contain detailed transactional data.

Schedule A explains where contributions come from. If you are interested in individual donors, this will be the endpoint you use.

For the Schedule A aggregates, "memoed" items are not included to avoid double counting.

Schedule B explains how money is spent.



Package Files

api.go candidates.go client.go doc.go errors.go filings.go pagination.go util.go


const (
    Incumbent  = IncumbentChallenge("I")
    Challenger = IncumbentChallenge("C")
    Open       = IncumbentChallenge("O")
const (
    PresentCandidate = CandidateStatus("C")
    FutureCandidate  = CandidateStatus("F")
    NotYetACandidate = CandidateStatus("N")
    PriorCandidate   = CandidateStatus("P")
const (
    House     = Office("H")
    Senate    = Office("S")
    President = Office("P")
const (
    Document24HourContributionNotice                         = DocumentType("2")
    Document48HourContributionNotice                         = DocumentType("4")
    DocumentDebtSettlementStatement                          = DocumentType("A")
    DocumentAcknowledgmentofReceiptofDebtSettlementStatement = DocumentType("B")
    DocumentRFAIDebtSettlementFirstNotice                    = DocumentType("C")
    DocumentCommissionDebtSettlementReview                   = DocumentType("D")
    DocumentCommissionResponseTODebtSettlementRequest        = DocumentType("E")
    DocumentAdministrativeTermination                        = DocumentType("F")
    DocumentDebtSettlementPlanAmendment                      = DocumentType("G")
    DocumentDisavowalNotice                                  = DocumentType("H")
    DocumentDisavowalResponse                                = DocumentType("I")
    DocumentConduitReport                                    = DocumentType("J")
    DocumentTerminationApproval                              = DocumentType("K")
    DocumentRepeatNonFilerNotice                             = DocumentType("L")
    DocumentFilingFrequencyChangeNotice                      = DocumentType("M")
    DocumentPaperAmendmenttoElectronicReport                 = DocumentType("N")
    DocumentAcknowledgmentofFilingFrequencyChange            = DocumentType("O")
    DocumentRFAIDebtSettlementSecond                         = DocumentType("S")
    DocumentMiscellaneousReportTOFEC                         = DocumentType("T")
    DocumentRepeatViolationNotice_441A_Or_441B               = DocumentType("V")
    DocumentNoticeofPaperFiling                              = DocumentType("P")
    DocumentF3LFilingFrequencyChangeNotice                   = DocumentType("R")
    DocumentAcknowledgmentofF3LFilingFrequencyChange         = DocumentType("Q")
    DocumentUnregisteredCommitteeNotice                      = DocumentType("U")


var (
    ErrUnauthorized = errors.New("openfec: unauthorized")
    ErrNotFound     = errors.New("openfec: not found")
var BaseURL = ""

BaseURL is the common URL prefix for all API requests.

func ToValues Uses

func ToValues(in interface{}) (url.Values, error)

type APIError Uses

type APIError struct {
    Err struct {
        Code    string `json:"code,omitempty"`
        Message string `json:"message,omitempty"`
    } `json:"error,omitempty"`

func (*APIError) Error Uses

func (e *APIError) Error() string

type Candidate Uses

type Candidate struct {
    ActiveThrough          int    `json:"active_through,omitempty"`
    CandidateID            string `json:"candidate_id,omitempty"`
    CandidateStatus        string `json:"candidate_status,omitempty"`
    CandidateStatusFull    string `json:"candidate_status_full,omitempty"`
    Cycles                 []int  `json:"cycles,omitempty"`
    District               string `json:"district,omitempty"`
    ElectionYears          []int  `json:"election_years,omitempty"`
    IncumbentChallenge     string `json:"incumbent_challenge,omitempty"`
    IncumbentChallengeFull string `json:"incumbent_challenge_full,omitempty"`
    Name                   string `json:"name,omitempty"`
    Office                 string `json:"office,omitempty"`
    OfficeFull             string `json:"office_full,omitempty"`
    Party                  string `json:"party,omitempty"`
    PartyFull              string `json:"party_full,omitempty"`
    State                  string `json:"state,omitempty"`

type CandidateIter Uses

type CandidateIter struct {
    // contains filtered or unexported fields

func (*CandidateIter) Err Uses

func (i *CandidateIter) Err() error

func (*CandidateIter) Next Uses

func (i *CandidateIter) Next() bool

func (*CandidateIter) Value Uses

func (i *CandidateIter) Value() *Candidate

type CandidateQuery Uses

type CandidateQuery struct {
    Sort               string               `json:"sort,omitempty"`
    SortHideNull       bool                 `json:"sort_hide_null,omitempty"`
    Party              string               `json:"party,omitempty"`
    IncumbentChallenge []IncumbentChallenge `json:"incumbent_challenge,omitempty"`
    Cycle              []int                `json:"cycle,omitempty"`
    Year               int                  `json:"year,omitempty"`
    CandidateStatus    []CandidateStatus    `json:"candidate_status,omitempty"`
    State              string               `json:"state,omitempty"`
    District           int                  `json:"district,omitempty"`
    Office             []Office             `json:"office,omitempty"`
    Name               string               `json:"name,omitempty"`
    CandidateID        string               `json:"candidate_id,omitempty"`
    Query              string               `json:"q,omitempty"`

type CandidateStatus Uses

type CandidateStatus string

type Client Uses

type Client struct {
    APIKey string
    // contains filtered or unexported fields

Client is the primary struct that this package provides. It represents the connection to the OpenFEC API.

func NewClient Uses

func NewClient(APIKey string) (*Client, error)

NewClient creates a new Client to interact with the OpenFEC API.


apiKey := os.Getenv("DATA_GOV_API_KEY")
client, err := openfec.NewClient(apiKey)
if err != nil {
candidates, err := client.GetCandidates(nil)
fmt.Printf("err:%v\ntype1:%T\n", err, candidates)



func (*Client) GetCandidateFilings Uses

func (c *Client) GetCandidateFilings(candidateID string) (*FilingIter, error)

GetCandidateFilings fetches filings for a given Candidate ID.

func (*Client) GetCandidates Uses

func (c *Client) GetCandidates(query *CandidateQuery) (*CandidateIter, error)

GetCandidates fetches a list of basic candidate information.

query is an optional parameter that supplies additional parameters

Fetch basic information about candidates, and use parameters to filter results to the candidates you're looking for. Each result reflects a unique FEC candidate ID. That ID is particular to the candidate for a particular office sought. If a candidate runs for the same office multiple times, the ID stays the same. If the same person runs for another office — for example, a House candidate runs for a Senate office — that candidate will get a unique ID for each office.


apiKey := os.Getenv("DATA_GOV_API_KEY")
if apiKey == "" {
    apiKey = "DEMO_KEY"
client, err := openfec.NewClient(apiKey)
if err != nil {
query := &openfec.CandidateQuery{
    Sort:   "name",
    Office: []openfec.Office{openfec.President},
    Cycle:  []int{2016},
candidates, err := client.GetCandidates(query)
if err != nil {
for candidates.Next() {
    c := candidates.Value()
    _ = c
    // do something with each candidate here



func (*Client) TraceOff Uses

func (c *Client) TraceOff()

TraceOff turns on API response tracing

func (*Client) TraceOn Uses

func (c *Client) TraceOn(logger *log.Logger)

TraceOn turns on API response tracing to the given logger.

type DocumentType Uses

type DocumentType string

type Filing Uses

type Filing struct {
    AmendmentIndicator           string       `json:"amendment_indicator,omitempty"`
    BeginningImageNumber         string       `json:"beginning_image_number,omitempty"`
    CandidateID                  string       `json:"candidate_id,omitempty"`
    CandidateName                string       `json:"candidate_name,omitempty"`
    CashOnHandBeginningPeriod    int          `json:"cash_on_hand_beginning_period,omitempty"`
    CashOnHandEndPeriod          int          `json:"cash_on_hand_end_period,omitempty"`
    Committee                    string       `json:"committee,omitempty"`
    CommitteeID                  string       `json:"committee_id,omitempty"`
    CommitteeName                string       `json:"committee_name,omitempty"`
    CoverageEndDate              string       `json:"coverage_end_date,omitempty"`
    CoverageStartDate            string       `json:"coverage_start_date,omitempty"`
    Cycle                        int          `json:"cycle,omitempty"`
    DebtsOwedByCommittee         int          `json:"debts_owed_by_committee,omitempty"`
    DebtsOwedToCommittee         int          `json:"debts_owed_to_committee,omitempty"`
    DocumentDescription          string       `json:"document_description,omitempty"`
    DocumentType                 DocumentType `json:"document_type,omitempty"`
    DocumentTypeFull             string       `json:"document_type_full,omitempty"`
    ElectionYear                 int          `json:"election_year,omitempty"`
    EndingImageNumber            string       `json:"ending_image_number,omitempty"`
    FileNumber                   int          `json:"file_number,omitempty"`
    FormType                     string       `json:"form_type,omitempty"`
    HousePersonalFunds           int          `json:"house_personal_funds,omitempty"`
    NetDonations                 int          `json:"net_donations,omitempty"`
    OppositionPersonalFunds      int          `json:"opposition_personal_funds,omitempty"`
    Pages                        int          `json:"pages,omitempty"`
    PdfURL                       string       `json:"pdf_url,omitempty"`
    PreviousFileNumber           string       `json:"previous_file_number,omitempty"`
    PrimaryGeneralIndicator      string       `json:"primary_general_indicator,omitempty"`
    ReceiptDate                  string       `json:"receipt_date,omitempty"`
    ReportType                   string       `json:"report_type,omitempty"`
    ReportTypeFull               string       `json:"report_type_full,omitempty"`
    ReportYear                   int          `json:"report_year,omitempty"`
    RequestType                  string       `json:"request_type,omitempty"`
    SenatePersonalFunds          int          `json:"senate_personal_funds,omitempty"`
    SubID                        int          `json:"sub_id,omitempty"`
    TotalCommunicationCost       int          `json:"total_communication_cost,omitempty"`
    TotalDisbursements           int          `json:"total_disbursements,omitempty"`
    TotalIndependentExpenditures int          `json:"total_independent_expenditures,omitempty"`
    TotalIndividualContributions int          `json:"total_individual_contributions,omitempty"`
    TotalReceipts                int          `json:"total_receipts,omitempty"`
    TreasurerName                string       `json:"treasurer_name,omitempty"`
    UpdateDate                   string       `json:"update_date,omitempty"`

type FilingIter Uses

type FilingIter struct {
    // contains filtered or unexported fields

func (*FilingIter) Err Uses

func (i *FilingIter) Err() error

func (*FilingIter) Next Uses

func (i *FilingIter) Next() bool

func (*FilingIter) Value Uses

func (i *FilingIter) Value() *Filing

type FilingQuery Uses

type FilingQuery struct {
    CandidateID  string `json:"candidate_id,omitempty"`
    Sort         string `json:"sort,omitempty"`
    SortHideNull bool   `json:"sort_hide_null,omitempty"`

type IncumbentChallenge Uses

type IncumbentChallenge string

type Office Uses

type Office string

Package openfec imports 8 packages (graph). Updated 2016-07-21. Refresh now. Tools for package owners.