Last week, my colleague Eric gave a short talk about JSON that he originally presented during Open Data Day. The goal of the presentation, with notes available here on Gist, was to walk the non-developer staff at Sunlight through URL structures, then to the similar framing of JSON and finally how to do some basic calls to an API. I found it quite useful, not only in how I discuss Sunlight’s APIs, but in enabling me to pursue silly projects with reduced badgering of my technically-minded colleagues. By the end of the day, I’d set up a Twitter account that automatically wishes members of Congress a happy birthday when their special day arrives.

The prerequisites to follow along are registering for a Sunlight API key, installing a JSON viewer for your browser (here is what I used in Chrome), the gumption to click some links and the patience to read this post. Looking good so far.

From the URL to JSON

Under Eric’s tutelage, the class started out by looking over the key/value pair that’s laid out plainly in a search (or query) for sunlight in the URL structure of `flickr.com/search/?q=sunlight` and then made our way to what data is made available by Sunlight in the Congress API documentation. We then jumped right in and made a simple call to walk through what’s on screen. The most basic call was to simply see results for /legislators, seen to the left, by typing this into the URL bar:

> https://congress.api.sunlightfoundation.com/legislators?apikey=[YOUR API KEY]

From there, we pared down results by specifying the data we wanted with the `fields` filter and a comma separated list of the fields, such as `first_name`, `phone` or `twitter_id`. Then we fiddled with the ability to change how things are sorted, so you can add something like `order=last_name__asc` to return data alphabetically by last name. It was quite straightforward and once we shifted to the bills and votes section, it was obvious the many quick research opportunities these types of queries could answer. The class next learned how to build a query that gets pretty specific results, with hopes to answer, “Which bills in the Senate had an overwhelming majority voting ‘Yea’?” We slowly worked our way through with the operators available and ended up with a query in the URL bar that looked like this:

> https://congress.api.sunlightfoundation.com/votes?apikey=[YOUR API KEY]&breakdown.total.Yea__gte=70&chamber=senate

If you slowly break out each section of the URL, you can start to comprehend the parameters of the results. I was amazed how easy it was to get quite specific data by just stacking a bunch of fields you’re interested in into the URL bar. I honestly still don’t look at a long URL and immediately see what it’s asking, but I’m getting more familiar with how to unwrap the pile of keys and values into things I’m familiar with and slowly build my own.

From the API to a calendar

During class I thought of a few simple questions and went about seeing if I could get the API to output results. One idea was to isolate names, birth dates and Twitter accounts through the Congress API to create a calendar and then make a Twitter account to wish politicians a happy birthday. I thought I could do it, so I did it.

The first step was building the right API call, which for this project was essentially just isolating fields I wanted from current legislators. Here’s what I ended up building:

https://congress.api.sunlightfoundation.com/legislators?apikey=[YOUR API KEY]&fields=last_name,first_name,title,birthday,twitter_id&per_page=all

I then selected all and copied the results into Eric’s helpful JSON to CSV converter so I could save a file of the data to my desktop and eventually build a calendar. I did some research on various calendar formats and realized that Google Calendar and Apple’s Calendar app use a format called iCal and, fortunately, there’s a great free converter from CSV to iCal. I shifted around the columns of my spreadsheet to match the sample file from the CSV to iCal tool and created a nice little iCal file where the event names were the politicians’ title (Rep. or Sen.) with their full names and the event description was their Twitter handle. Unfortunately, when I imported that file to my Google Calendar, it created events only on the day politicians were born, not recurring events each year.

Building the bot

I solved this problem after looking up what the code for recurring events is in the iCal data format and discovered I could open it in a text editor and just do a “find and replace” on the event end date with a line saying `RRULE:FREQ=YEARLY`. That did the trick and when I imported it again into Google Calendar, it made a nice pretty yearly birthday listing that you can see here. I then created this IFTTT recipe that sends out a tweet with the format: “Happy birthday {{Event Title}} @{{Event Description}}!”

The next challenge was that the IFTTT recipe is triggered 15 minutes before the event on your calendar, so the bot’s first celebratory tweets all went out around 11:45 p.m. the night before the member’s birthdays. I adjusted my Google Calendar time zone to Hawaii and so now new birthday greetings come first thing in the morning at 6 a.m. Then I spent some well-earned time photoshopping a Twitter avatar of a birthday candle on the Capitol Building’s dome, selecting a patriotic header image and the perfect emoji for a background.

The @congressbdaybot is fully operational, with at least one successful congressional connection as Rep. Patrick Murphy, D-Fla., favorited the bot’s greetings. My long term goal for the project is to have a member of Congress retweet a greeting and later delete it, making it available forever on Sunlight’s Politwoops project.