Hacking Twitter Competitions: Automatically Tracking Followers Count

Just before Christmas, a Chicago Food Truck decided to give away free sandwiches for a year to their 1000th Twitter follower.

You know I had to try.

After checking it a few times over a 15 minute period or so, I noticed that the follower count was increasing very slowly. I knew I wouldn’t have the diligence to continue checking, so I decided to write a script that would do the check and notify me every ten minutes or so. Since I’m on a Mac, I decided to use Growl for these notifications.

In this post, I’ll walk you through how to automatically check a Twitter user’s follower count and get a Growl notification periodically.

What You Need

• Twitter API Key: to talk to the Twitter API
• Curl: for making HTTP requests over the interwebs
• jq: to parse the API responses; “like sed for JSON data”
• Growl: display notifications on Mac OS X
• growlnotify: command-line tool to send notifications to Growl
• Cron: run a command periodically

You’ll be checking the number of followers using the Twitter API. Most of the Twitter API requires authentication, including the endpoint we’ll be using, so you’ll need to create a new Twitter app to get an API key. The setup is straight-forward, as you can see.

Unfortunately, this gives you an OAuth consumer key and secret but you still need to go through the OAuth flow to get the Access Token used for the actual API requests. Luckily, Twitter supports OAuth2 for “application-only authentication” (when you don’t need access to a user’s private stuff). Getting an access token with OAuth2 is much easier than it was for the original OAuth; you can do it with just a Base64 encoder and Curl.

The tl;dr for the above Twitter auth tutorial is to use your app’s consumer key and secret for HTTP Basic Authentication against the Bearer Token Request endpoint. This will give you a new Bearer Token (or return your existing token if it’s still valid). I’ll let you read the details yourself.

With your shiny new Bearer Token in hand, you can now call the GET users/show Twitter endpoint to fetch a LOT of data about a twitter user, including their follower count.

curl -s "https://api.twitter.com/1.1/users/show.json?screen_name=Cheesies_Truck" \
  -H "Authorization: Bearer <token>"

This comes back as a big JSON document. Try it yourself (or checkout the doc linked above) to see the giant JSON response from this call. The only thing we care about here is the followers_count though. Let’s use jq to easily parse it out. If you’re not familiar with jq yet, you should get familiar with it. Its an awesome command-line tool to parse and transform JSON data. (This assumes you’ve already installed jq and added it to your PATH.)

curl -s "https://api.twitter.com/1.1/users/show.json?screen_name=Cheesies_Truck" \
  -H "Authorization: Bearer <token>" \
  | jq ".followers_count"

This prints a single number to stdout, like 968. Now we can display this in a Growl notification using growlnotify.

curl -s "https://api.twitter.com/1.1/users/show.json?screen_name=Cheesies_Truck" \
  -H "Authorization: Bearer <token>" \
  | jq ".followers_count" \
  | xargs -I {} growlnotify -t "Cheesies Count is {}"

It took a bit of fiddling to find out the best growlnotify incantation. If you pipe the output of jq in directly to growlnotify, it becomes the body of the notification. While this is okay if you’re actually going to see all the notifications, the body doesn’t show up in the rollups or history like it does if you put the number in the notification title with the -t flag as shown. I wanted to be able to quickly glance back at the history in case I stepped away from my computer. (I like to sleep and eat occasionally too.)

All that’s left is to run this every ten minutes as a shell script with cron.

But wait! Cron runs in a funky environment which doesn’t inherit the current shell’s PATH. So we have to setup the correct PATH ourselves. (These paths are local to where I have things installed. Be sure to update them with your own installation setup.)

PATH=$PATH:/usr/bin/:/usr/local/bin/:$HOME/bin
curl -s "https://api.twitter.com/1.1/users/show.json?screen_name=Cheesies_Truck" \
  -H "Authorization: Bearer <token>" \
  | jq ".followers_count" \
  | xargs -I {} growlnotify -t "Cheesies Count is {}"

I’ve saved this file as get_cheesies_followers_count.sh in “bin/” in my home directory. Now we just need to add this to your crontab.

You can edit your crontab in your standard EDITOR by running

crontab -e

Just add this entry to run it every ten minutes. Tweak the cron to run it more or less often as you please (like running every minute for testing).

*/10 * * * * /bin/bash $HOME/bin/get_cheesies_followers_count.sh

Now every 10 minutes you’ll see something like this:

There you have it, folks! An easy way to track any Twitter user’s followers! Now, back to (dreaming of) my sandwiches…*

* I didn’t actually win. Much like last-minute eBay bidding, the followers count rapidly increased in the few minutes just before the 1000th follower. Once they hit something like 980, it quickly escalated past the 1000th mark. Since I was only checking every 15 minutes, I missed out on all this action. But it was still a fun little hack that I thought I’d share.