Influence Data APIs

by

Followers of this blog are probably already aware of two of the main sites developed by our Data Commons team: TransparencyData.com and InfluenceExplorer.com. Both sites present a variety of influence related data sets, such as campaign finance, federal lobbying, earmarks and federal spending. Influence Explorer provides easy to use overview information about politicians, companies, industries and prominent individuals, while Transparency Data allows users to search and download detailed records from various influence data sets.

In this blog post I want to show how easy it can be to use the public APIs for both sites to integrate influence data into your own projects. I’ll walk through a couple examples and show how to use both the RESTful API and the new Python wrapper. I’ll assume you’re already familiar with the basics of RESTful APIs. I’ve used a fake key abc123 in the examples. To run them yourself you’ll need to replace that with your own free Sunlight API key, available here.

Using the Influence Explorer API

As a first example, consider a political blog where content authors annotate articles with names of politicians relevant to the article. We can use the Influence Explorer APIs to automatically add an overview of the politician’s fundraising in the last election. We’ll make two API calls:

1) Search for the politician. Influence Explorer provides full-text search on names: 

http://transparencydata.com/api/1.0/entities.json?apikey=abc123&search=john%20boehner

or, using the Python wrapper:

>>> from influenceexplorer import InfluenceExplorer
>>> api = InfluenceExplorer('abc123')
>>> api.entities.search('john boehner')

This returns basic information about matching entities:

[
    {
        "name": "Friends of John Boehner", 
        "type": "organization", 
        "lobbying_firm": false, 
        "firm_income": 0.0, 
        "total_received": 0.0, 
        "seat": null, 
        "state": null, 
        "count_lobbied": 0, 
        "count_received": 0, 
        "party": null, 
        "total_given": 549673.0, 
        "count_given": 426, 
        "id": "53ecb66245a64f0b989259b63f50bd9f", 
        "non_firm_spending": 0.0
    }, 
    {
        "name": "John Boehner (R)", 
        "type": "politician", 
        "lobbying_firm": null, 
        "firm_income": 0.0, 
        "total_received": 17717382.0, 
        "seat": "federal:house", 
        "state": "OH", 
        "count_lobbied": 0, 
        "count_received": 16855, 
        "party": "R", 
        "total_given": 0.0, 
        "count_given": 0, 
        "id": "f990d08287c34c389cfabe3cbf3dde99", 
        "non_firm_spending": 0.0
    }
]

With full-text search on a name you can of course have false matches. In this case your client would probably want to keep only results with type == 'politician', and potentially also filter on fields such as seat or state to make sure you have the correct entity.

2) Retrieve overview information. In this example we’ll retrieve a list of the top industries that contributed to the politician. The entity methods are all accessed by the entity id given in the search results. John Boehner’s ID is f990d08287c34c389cfabe3cbf3dde99.

http://transparencydata.com/api/1.0/aggregates/pol/f990d08287c34c389cfabe3cbf3dde99/contributors
/industries.json?cycle=2010&limit=5&apikey=abc123

or

>>> api.pol.industries('f990d08287c34c389cfabe3cbf3dde99', cycle=2010, limit=5)

The results give the name of each industry and the total amount given to the politician:

[
    {
        "count": "433", 
        "amount": "309055.00", 
        "id": "0171a70d50e8471d94c6e7083ca154c8", 
        "name": "EMPLOYER LISTED/CATEGORY UNKNOWN", 
        "should_show_entity": false
    }, 
    {
        "count": "157", 
        "amount": "244590.00", 
        "id": "8ada0fc2d6994f2ab06c7e025dff2284", 
        "name": "INSURANCE", 
        "should_show_entity": true
    }, 
    {
        "count": "107", 
        "amount": "207650.00", 
        "id": "0af3f418f426497e8bbf916bfc074ebc", 
        "name": "SECURITIES & INVESTMENT", 
        "should_show_entity": true
    }, 
    {
        "count": "429", 
        "amount": "199582.00", 
        "id": "b21467ae32924f84ada9076535401a91", 
        "name": "RETIRED", 
        "should_show_entity": false
    }, 
    {
        "count": "91", 
        "amount": "175450.00", 
        "id": "a05a0d06f6814b31bece35a81fcb40c7", 
        "name": "HEALTH PROFESSIONALS", 
        "should_show_entity": true
    }
]

Every chart or figure on Influence Explorer is available in the API. A list of all available methods is available in the Python docs.

Using the Transparency Data API

The Influence Explorer APIs discussed above provide summary information for particular entities. The Transparency Data API, in contrast, is used to get down to the individual transaction records that make up the data. The particular data sets provided at the moment are campaign finance (both federal-level and state-level), federal lobbying, earmarks, and federal grants and contracts, with more data sets to be added in the future. Unlike the Influence Explorer API, the Transparency Data API has no notion of an entity; all data access is through search.

In this example we’ll show how a single API call can be used to display a page that shows the user all federal earmarks directed at his or her city. We’ll assume the user’s city has already been determined, either through geolocation or user input. A simple search will give all the earmarks targeted at that city:

http://transparencydata.com/api/1.0/earmarks.json?city=seattle&state=WA&apikey=abc123

or

>>> from transparencydata import TransparencyData
>>> api = TransparencyData('abc123')
>>> api.earmarks(city='Seattle', state='WA')

The method returns a list of earmarks from Seattle, WA:

[
    {
        "budget_amount": "110000000.00", 
        "description": "Sound Transit-University Link LRT Extension, Seattle, WA", 
        "recipients": "", 
        "notes": "", 
        "bill": "Transportation-Housing and Urban Development", 
        "undisclosed": "", 
        "locations": "Seattle, WA", 
        "fiscal_year": 2010, 
        "omni_amount": "0.00", 
        "house_amount": "110000000.00", 
        "senate_amount": "110000000.00", 
        "presidential": "m", 
        "members": "Sen. Patty Murray (D-WA)", 
        "bill_section": "Federal Transit Administration", 
        "bill_subsection": "Capital Investment Grants", 
        "final_amount": "110000000.00"
    }, 
    {
        "budget_amount": "0.00", 
        "description": "Global UAS Networking and Interoperability System (GUNIS)", 
        "recipients": "COCO Communications", 
        "notes": "", 
        "bill": "Defense", 
        "undisclosed": "", 
        "locations": "Seattle, WA", 
        "fiscal_year": 2010, 
        "omni_amount": "0.00", 
        "house_amount": "0.00", 
        "senate_amount": "4500000.00", 
        "presidential": "", 
        "members": "Sen. Patty Murray (D-WA)", 
        "bill_section": "Research, Development, Test & Evaluation", 
        "bill_subsection": "Air Force", 
        "final_amount": "4000000.00"
    }, 
    ...
]

Similar methods are available for campaign contributions, lobbying activity, and federal grants and contracts. A more complete list is available in the Python docs or on TransparencyData.com’s docs.

Other Uses

Transparency Data and Influence Explorer are already built entirely on the public APIs. We’ve also used the APIs in projects such as Poligraft, Checking Influence and Politiwidgets. With the release of the Python API wrapper it’s now even easier to add political influence data to your own projects. If you have any questions or want to let us know about something you’ve built, feel free to contact us on the Sunlight Labs list or email me directly.