Sunlight Foundation

A little while ago Ethan blogged about how to use our Influence Explorer APIs. It was a great intro to just how easy it is to start pulling influence data from our systems and into your projects.

But of course that's just one of several APIs that we offer. A couple of weeks ago I responded to an email from someone interested in matching a dataset of zip codes to congressional districts. This is a pretty common task for people doing research, or building advocacy websites, or otherwise trying to link citizens to their elected representatives. It also happens to be a problem that our APIs are perfectly suited to solving.

So here's an example that I wrote to try to show a non-programmer how to get up to speed with our APIs in Python. If you're on OS X or a Linux system, you've already got Python installed. If you're on Windows, you'll need to jump through a few more hoops -- this blog post should be helpful (it's probably a good idea to stick with a Python version earlier than 3.0). Hopefully this will show just how simple it can be to start using our services.

This particular code is oriented toward taking a CSV file with zip codes and adding information about the congressional districts associated with each zip. There's sample data included as well -- just a random assortment of zipcodes -- to help you see how everything works. You shouldn't need much more than a free API key and a command line prompt.

This code interfaces with our API through the use of a helper library. I've included that file too, but if you want the most up-to-date version you can find it here (Rubyists: we have a gem as well). I should also note that the code doesn't follow optimal conventions -- for instance, hardcoding the input filename is not how I'd normally do things -- but I think it's a bit easier to follow this way. I've tried to add a lot of comments.

For this exercise I assumed that the zip is in the row's final column -- the row[-1] code at line 26 determines this. This is the case for the sample file, but if you have your own CSV to process, it might not be. But it's easy to change this! If the zip is in the second-to-last column, for instance, you can use row[-2], and so on. You can also use positive addressing: row[0] is the first column, row[1] the second, etc. Please make sure that whatever CSV you use doesn't begin with a header row, as this will confuse our API and throw an error ("Dear API: which congressional districts fall within the zipcode with the number 'Zipcode'?").

To use the script:

1. Obtain a free API key from services.sunlightlabs.com.

2. Download this zip file and uncompress it. Place its contents in the same same directory as the CSV file you want to process (or just use the included one, if you're trying things out -- you can put them in any old folder).

3. Open getdistricts.py in a decent text editor, like TextWrangler (OS X), vim/emacs (Linux), or Notepad++ (Windows).

4. Insert your API key in the appropriate spot on line 4.

5. Change the value of the INPUT_FILENAME variable on line 5 to match your desired CSV's filename.

6. In a terminal window, navigate to the appropriate directory and run the script by typing "python getdistricts.py"

You should see output as a query is made for each zip code (zip codes that have already been looked up will be cached). When the process is complete, a file called output.csv will be present in the same directory. It will contain the same columns as the source file, plus two new columns at each row's end: one with the number of districts within that zipcode, and another with those districts delimited with semicolons.

That's it! Now, yes, if you're coming to this as a complete newbie, following these steps probably won't make you instantly comfortable with programming. But for those who've tinkered but never tangled with a real API, hopefully this will go some of the way toward showing how easy it is to use our services. And don't forget: if you run into trouble, we're here to help.