Influence Explorer Text API

The API that powers the real-time textual analysis behind the Sunlight Foundation's Inbox Influence is called the Influence Explorer Text API, and it is available for general public use in applications that require extraction of politically relevant entities from text on either the client or server side. The data supplied by this API is a subset of the data available in Sunlight's Transparency Data, and provides summary information about campaign finance, lobbying, fundraising, and other influence-related areas of interest.

Getting Started

Technical Information

The Influence Explorer Text API is nominally RESTful, but doesn't provide a notion of resources, per se, and at this time exposes only one endpoint that is suitable for public consumption. An API key is required for use of this API, and unlike some other Sunlight APIs that allow API keys to be submitted as POST parameters or HTTP headers, the Text API requires that API keys be submitted as GET parameters, regardless of the HTTP method of the request.

The API accepts either GET or POST requests, returns JSON, and supports both JSONP and Cross-Origin Resource Sharing (CORS) for facilitating client-side cross-domain requests. JSONP has better cross-browser support and proxy traversal features, but as it allows only GET parameters, which generally have browser-imposed length constraints, it is less suitable for the kinds of long messages for which this API is often useful. The Inbox Influence application uses JSONP for messages shorter than 2000 characters and CORS for longer ones; client-side application developers may want to choose a similar trade-off.

At this time, the Text API only allows SSL requests. The text submitted for analysis is not retained, though Sunlight does store limited non-text information such as API keys, user agents strings and IP addresses for analytics purposes.

Endpoint

The current public API endpoint for the Text API is https://inbox.influenceexplorer.com/contextualize. It accepts the following parameters:

  • apikey: a Sunlight Services API key (required; must be a GET parameter)
  • text: the text to be analyzed (required; can be a GET or POST parameter)
  • callback: the name of the callback function in which the response should be wrapped for JSONP requests (optional; must be a GET parameter if supplied)

Included below is an annotated sample of the output of the API. String literals in this sample will appear as written in the response. Variables in this sample will be indicated in angle brackets as <type>, where type is one of "string," "float," or one of the other valid JSON types. In actual responses, some portions of the response may not be relevant, as not all parts of the tree are relevant to all entity types. In general, keys will be present with null values, rather than absent, if they are not relevant to the entity in question, so as to deal with browser idiosyncrasies regarding the handling of undefined values. Order is not guaranteed, and may not appear as it does below. For more information on how the totals supplied by this API are calculated, see Influence Explorer's data description.

{
"entities": [
List of all Transparency Data entities found within the text.
{
"matched_text": [
<string>,
...
The entity's name as it appears in the source text; suitable for search and replace. This list will contain multiple strings if multiple variants of the same entity's name occur within the text.
],
"entity_data": {
"name": <string>,
The entity's name after automated standardization for order, case, etc.
"raw_name": <string>,
The entity's name as it appears in the original source data (CRP, NIMSP, etc.)
"type": <string>,
One of "politician", "organization", or "individual"
"id": <string>,
Transparency Data ID for the entity; necessary for doing further TD API calls or constructing Influence Explorer link URLs.
"slug": <string>,
Slug for constructing Influence Explorer link URLs.
"bioguide_id": <string>,
"crp_id": <string>,
"held_seat": <boolean>,
"seat": <string>,
Transparency Data designation for a politician's seat (for example, "federal:president"). In cases where a politician has held or run for multiple seats, the system prefers seats held to seats for which the politician ran and lost, newer ones to older ones, and federal to state.
"seat_label": <string>,
English-language representation of the seat (e.g., "President").
"affiliated_organizations": [
{
"name": <string>,
"type": <string>,
"id": <string>,
"slug": <string>
For individuals, a list of organizations with which the person has some affiliation. Will be null for organizations.
},
...
],
"campaign_finance": {
"contribution_total": <number>,
For politicians, the total number of dollars received. For organizations and individuals, the total spent.
"recipient_breakdown": {
"dem": <number>,
"rep": <number>,
"other": <number>
For individuals and organizations, the number of dollars spent on members of each party. Null for politicians.
},
"contributor_local_breakdown": {
"in_state": <number>,
"out_of_state": <number>
For politicians, the number of dollars spent by contributors from within the politician's state versus out of state. Null for organizations and individuals.
},
"contributor_type_breakdown": {
"individual": <number>,
"pac": <number>
For politicians, the number of dollars spent by individual contributors versus political action committees. Null for organizations and individuals.
},
"top_industries": [
{
"amount": <number>,
"name": <string>,
"type": <string>,
"id": <string>,
"slug": <string>
For politicians, a list of the top industries (up to five) to have donated to the politician.
},
...
],
},
"upcoming_fundraisers": [
{
"entertainment": ,
"start_date": <string>,
"start_time": <string>,
"venue": <string>,
"partytime_id": <string>,
"contributions_info": <string>,
"make_checks_payable_to": <string>,
For politicians, a list of one or more upcoming fundraisers, supplied by Sunlight's Political Party Time service.
"beneficiaries": [
<string>,
...
],
"hosts": [
<string>,
...
]
},
...
],
"lobbying": {
"is_lobbyist": <boolean>,
For individuals, whether or not the individual is a lobbyist. Always false for other types.
"is_lobbying_firm": <boolean>,
For organizations, whether or not the organization is a lobbying firm. Always false for other types.
"expenditures": <number>,
For lobbying firms and lobbyists, how much the entity was paid to lobby. For non-lobbying-firm organizations, how much the organization spent on lobbying.
"top_issues": [
{
"count": <number>,
"issue": <string>
For lobbying firms and lobbyists, the top issues (up to five) for which the entity was hired to lobby, and the number of lobbying registrations for each. For non-lobbying-firm organizations, the top issues for which they hired lobbyists, and their counts.
},
...
],
"clients": [
{
"count": <number>,
"name": <string>,
"type": <string>,
"id": <string>,
"slug": <string>
For lobbying firms and lobbyists, their top clients (up to five) and the number of registrations for each. Null for other entities.
},
...
]
}
}
},
...
]
}


Terms of Use

Much of the data returned by the Influence Explorer Text API is provided, variously, by the Federal Election Commission, the Center for Responsive Politics, and the National Institute for Money in State Politics, and as such is governed by their respective rules, restrictions, and license terms. See the Transparency Data license to learn more about these requirements.

At this time, the Sunlight Foundation is not enforcing any request or bandwidth limits on the use of the Text API, but reserves the right to do so in the future.