Capitol Words API
by speca

Capitol Words API

This documentation is for Version 1 of the Capitol Words API. Version 1 is currently the only version, and is actively maintained.

Base URI

http://capitolwords.org/api/1
Parameters

ascd

apikey
string required

A valid Sunlight labs API key. You can register for one here: http://services.sunlightlabs.com/accounts/register

Example:
<YOUR_API_KEY>
state
string optional

Limit results to members of Congress from the given state. Valid values: 2-letter state abbreviation, such as MD, VA, DC.

Example:
MD
party
string optional

Limit results to members of Congress from the given party. Valid values: R, D, I

Example:
R
chamber
string optional

The chamber to search. Default includes House, Senate and extensions of remarks. Valid values: house, senate, extensions

Example:
senate
date
string optional

Show results for only the given date. //todo provide example

start_date
string optional

Limit results to those on or after the given date.

end_date
string optional

Limit results to those on or before the given date.

Documentation
Getting started

Listed below are the public methods currently supported by the Capitol Words API.
All requests must be signed with a valid Sunlight labs API key.
You can register for one here: http://services.sunlightlabs.com/accounts/register

Discussion & Bugs

Sunlight API discussion takes place at the sunlightlabs-api-discuss google group. You can ask questions there, as well as alert the maintainers of bugs. If you have specific issues with the Capitol Words API, you can open a ticket directly at github.

API Methods
Phrase Time Series
GET /dates.json
Top Phrases by Entity
GET /phrases.json
Top Entities by Phrase
GET /phrases/{entity}.json
Text Search
GET /text.json
Phrase Time Series
GET /dates.json

Find the popularity of a phrase over a period of time. Standard arguments are supported.

Request parameters

phrase
string required

The phrase to search for.

Example:
street
bioguide_id
string optional

Limit results to the member of Congress with the given Bioguide ID.

mincount
string optional

Only return results where mentions are at or above the supplied threshold

percentages
boolean optional

Include the percentage of mentions versus total words in the result objects.
Default - false

Example:
false
granularity
string optional

The length of time covered by each result.
Valid values:

  • year
  • month
  • day (default)
Example:
day

Responses

200 OK
Body
Array of Date Object

Examples

Get a list of how many times the phrase “united states” appears in the Congressional Record on each day in the most recent Congress:

GET http://capitolwords.org/api/1/dates.json?phrase==united+states HTTP/1.1

Get a list of how many times the phrase “united States” appears in the Congressional Record on each day between Jan. 1, 2010, and June 1, 2010:

GET http://capitolwords.org/api/1/dates.json?phrase=united+states HTTP/1.1

Get a list of how many times the phrase “united states” appears in the Congressional Record in each month between January and June, 2010:

GET http://capitolwords.org/api/1/dates.json?phrase=united+states&granularity=month HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "results": [
        {
            "count": 14.0,
            "percentage": 0.058309037900874633,
            "total": 24010,
            "day": "1996-01-02",
            "raw_count": 14.0
        },
        {
            "count": 122.0,
            "percentage": 0.067791336044986786,
            "total": 179964,
            "day": "1996-01-04",
            "raw_count": 122.0
        },
        {
            "count": 198.0,
            "percentage": 0.13499693188791165,
            "total": 146670,
            "day": "1996-01-05",
            "raw_count": 198.0
        },
        {
            "count": 1.0,
            "percentage": 0.098135426889106966,
            "total": 1019,
            "day": "1996-01-08",
            "raw_count": 1.0
        }
    ]
}
show more
Top Phrases by Entity
GET /phrases.json

List the top phrases for a facet.

Request parameters

entity_type
string required

The entity type to get top phrases for. Valid values:

  • date
  • month
  • state
  • legislator
Example:
legislator
entity_value
string required

The value of the entity given in entity_type. Formats are as follows:

  • date: 2011-11-09
  • month: 201111
  • state: NY
  • legislator (bioguide id): L000551
n
number optional

The size of phrase, in words, to search for (up to 5).

Example:
3
page
number optional

The page of results to show. 100 results are shown at a time. To get more than 100 results, use the page parameter.

Example:
200
sort
string optional

The metric and direction to sort by. Valid values:

  • tfidf (default)
  • count

Both a metric and direction must be supplied, such as ‘sort=count asc’

Example:
count asc

Responses

200 OK
Body
Array
Object
tfidf
number
Example:
0.0000385965571248
count
number
Example:
5373
ngram
string
Example:
people

Examples

List the top words in July 2010 by count:

GET http://capitolwords.org/api/1/phrases.json?entity_type=month&entity_value=201007&sort=count+desc HTTP/1.1

List the top words for Nevada:

GET http://capitolwords.org/api/1/phrases.json?entity_type=state&entity_value=Nevada HTTP/1.1

List the top words for Barbara Lee:

GET http://capitolwords.org/api/1/phrases.json?entity_type=legislator&entity_value=L000551 HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

[
    {
        "tfidf": 3.8596557124800003e-05,
        "count": 5373,
        "ngram": "people"
    },
    {
        "tfidf": 1.30267768302e-05,
        "count": 3637,
        "ngram": "one"
    },
    {
        "tfidf": 2.52066478599e-05,
        "count": 3509,
        "ngram": "jobs"
    },
    {
        "tfidf": 1.17409333103e-05,
        "count": 3278,
        "ngram": "american"
    },
    ...snip...
]
show more
Top Entities by Phrase
GET /phrases/{entity}.json

Get the top (legislator|state|party|bioguide_id|volume|chamber)s for a phrase. Standard arguments are supported.

Path variables

entity
string required

Entity type for a phrase:

  • legislator
  • state
  • party
  • bioguide_id
  • volume
  • chamber
Example:
legislator

Request parameters

phrase
string required

The phrase to search for.

Example:
free+market
mincount
number optional

Only return results where mentions are at or above the supplied threshold

Example:
25
per_page
number optional

The number of results to return per page. The maximum is 50.

Example:
200
page
number optional

The page number to return.

Example:
3
sort
string optional

The metric on which to sort top results.

Note: Facet sorts in Solr are alphabetically ascending by facet or descending by count. The only valid values you can provide are count or :entity.

Example:
count

Responses

200 OK
Body
Array
Object
count
number
Example:
41
chamber
string
Example:
House

Examples

GET http://capitolwords.org/api/1/phrases/legislator.json?phrase=free+market HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "results": [
        {
            "count": 41.0,
            "chamber": "House"
        },
        {
            "count": 35.0,
            "chamber": "Senate"
        },
        {
            "count": 9.0,
            "chamber": "Extensions"
        }
    ]
}
Text Search
GET /text.json

Full-text search. Standard arguments are supported.

Request parameters

phrase
string optional

Text search arguments

Example:
obama+administration
title
string optional

A phrase to search the title of each CR document for.

bioguide_id
number optional

Limit results to the member of Congress with the given Bioguide ID.

Example:
200
cr_pages
number optional

The pages in the Congressional Record to search.

Example:
2
page
number optional

The page of results to show, 50 results are shown at a time.

Example:
190
sort
string optional

The value on which to sort the results. Options for this endpoint are:

  • speaker_state
  • congress
  • title
  • number
  • volume
  • chamber
  • session
  • id
  • speaker_party
  • date
  • bioguide_id
  • pages

Coupled with a direction, asc or desc. An example to sort by true chronological order and chamber (id works for this purpose) would be id desc.

Example:
id desc

Responses

200 OK

Returns a list of CR Documents and the total number found.

Body
Array
Object
speaker_state
string
Example:
NC
speaker_first
string
Example:
Virginia
congress
number
Example:
111
title
string
Example:
CULTIVATING AMERICAN ENERGY RESOURCES
origin_url
string
Example:
http://origin.www.gpo.gov/fdsys/pkg/CREC-2009-07-30/html/CREC-2009-07-30-pt1-PgH9197.htm
number
number
Example:
117
pages
string
Example:
H9197-H9203
volume
number
Example:
155
chamber
string
Example:
House
session
number
Example:
1
speaking
string
Example:
Well, I think that this is a great segue to talk about the other subject that we wanted to talk about tonight, which is health care, and what is happening with the health care debate.
capitolwords_url
string
Example:
http://capitolwords.org/date/2009/07/30/H9197_cultivating-american-energy-resources/
speaker_party
string
Example:
R
date
string
Example:
2009-07-30
bills
unknown
bioguide_id
string
Example:
F000450
order
number
Example:
14
speaker_last
string
Example:
Foxx
speaker_raw
string
Example:
ms. foxx

Examples

Get a list of pieces of text with the phrase obama administration in them:

GET http://capitolwords.org/api/1/text.json?phrase=obama+administration HTTP/1.1

Get a list of pieces of text by Republicans with the phrase “health care debate” in them:

GET http://capitolwords.org/api/1/text.json?phrase=health+care+debate HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "num_found": 347,
    "results": [
        {
            "speaker_state": "NC",
            "speaker_first": "Virginia",
            "congress": 111,
            "title": "CULTIVATING AMERICAN ENERGY RESOURCES",
            "origin_url": "http://origin.www.gpo.gov/fdsys/pkg/CREC-2009-07-30/html/CREC-2009-07-30-pt1-PgH9197.htm",
            "number": 117,
            "pages": "H9197-H9203",
            "volume": 155,
            "chamber": "House",
            "session": 1,
            "speaking": [
                "Well, I think that this is a great segue to talk about the other subject that we wanted to talk about tonight, which is health care, and what is happening with the health care debate."
            ],
            "capitolwords_url": "http://capitolwords.org/date/2009/07/30/H9197_cultivating-american-energy-resources/",
            "speaker_party": "R",
            "date": "2009-07-30",
            "bills": null,
            "bioguide_id": "F000450",
            "order": 14,
            "speaker_last": "Foxx",
            "speaker_raw": "ms. foxx"
        },
        ...snip...
    ]
}
show more
Data Reference
Date Object
Object
count
number

sfsdf

Example:
14
percentage
number
Example:
0.05830903790087463
total
number
Example:
24010
day
string
Example:
1996-01-02
raw_count
number
Example:
14
Methods: Phrase Time Series
Generic response
Object
results
Object data_container

Data container

Methods: Phrase Time Series Top Entities by Phrase
Response with Total
Object
results
Object data_container

Data container (//TODO provide better description)

num_found
string

total results found

Example:
247
Methods: Text Search