Are you as big of a fan of Paul Tagliamonte as I am? If so, then you are well aware of python-sunlight, his awesome, comprehensive Python API client for Sunlight’s APIs. The latest release includes a command line interface, or CLI, so you can interact with the Sunlight APIs directly from the shell. Cool, right?

To get started, install python-sunlight:

$ pip install sunlight

Next, you’ll need a Sunlight API key. Visit http://services.sunlightlabs.com/ and register for a key. Once you have your key, save it to a convenient location in your home directory.

$ echo "THIS_IS_MY_KEY" > ~/.sunlight.key

python-sunlight will automatically look in this file for your key. No need to set it in your program or pass it as a parameter to the command!

Okay, let’s do this…

$ sunlight
Usage: sunlight <service> <method> [<args>, ...]
Available services:
    influenceexplorer
    openstates
    capitolwords
    congress

So just by running sunlight we can see the endpoints that are available to us. Let’s use the congress endpoint to find out information about representatives.

$ sunlight congress
Usage: sunlight <service> <method> [<args>, ...]
Available methods:
    committee_detail
    committees
    committees_for_legislator
    districts_for_lat_lon
    districts_for_zip
    legislator_search
    legislators
    legislators_for_lat_lon
    legislators_for_zip

And there are all of the methods of the sunlight.congress module, exposed to us via the command line. Arguments to the API are passed via parameters.

$ sunlight congress legislators --state MD
[
  {
    "district": "6", 
    "title": "Rep", 
    "eventful_id": "", 
    "in_office": true, 
    "state": "MD", 
    "crp_id": "N00002017", 
    "official_rss": "", 
    …

The response from sunlight is the full JSON returned by the API call. It could potentially be a lot of data! Let’s write that JSON to a file so that we can do some more interesting stuff without making repeated calls to the API.

$ sunlight congress legislators --state MD > marylanders.json

Now that we’ve got that saved, let’s use the awesome JSON filtering utility, jq, to get at just the data we want. Install jq via the binaries provided on the web site or by brew install jq on Macs. The simplest thing to do with jq is to just return the JSON as-is.

$ cat marylanders.json | jq '.'
[
  {
    "district": "6", 
    "title": "Rep", 
    "eventful_id": "", 
    "in_office": true, 
    "state": "MD", 
    "crp_id": "N00002017", 
    "official_rss": "", 
    …

But what I really want to know are the names and Twitter screen names for each Marylander.

$ cat marylanders.json | jq '.[] | {firstname,lastname,twitter_id}'
{
  "twitter_id": "",
  "lastname": "Bartlett",
  "firstname": "Roscoe"
},
{
  "twitter_id": "SenatorCardin",
  "lastname": "Cardin",
  "firstname": "Benjamin"
},
{
  "twitter_id": "",
  "lastname": "Cummings",
  "firstname": "Elijah"
}
…

Well that was easy! And just to be clear, you can use jq directly with the sunlight command, no need to write the JSON response to disk first!

$ sunlight congress legislators --state MD | jq '.[] | {firstname,lastname,twitter_id}'

Anyway, that’s just a quick intro. You should check out the jq documentation and definitely register for a Sunlight API key!