JavaScript, Perl, IRC, and FourSquare

This week I wrote a script to check myself into foursquare venues. Being a C++ programmer for whom every microsecond counts, I don't get much opportunity to play around with scripted languages or internet services. So to accomplish this task, I had to teach myself enough JavaScript including using jQuery and JSON to interact with foursquare's API.

(By the way, I was going to put a foursquare logo here, but I read the trademark page and was so disgusted that I don't think I will)

Foursquare uses OAuth 2.0 to let a user give an application access to their foursquare account. This requires registering the application to get a ClientID, which is as simple as coming up with a name, and then using that ClientID in conjunction with the user's cooperation to generate an authentication token, which can then be used indefinitely to access the user's account. To reduce the risk of the application being spoofed, foursquare also requires a URL during registration, which it calls back during the authentication process.

Because of this callback model, I have to have a real web page on a publicly-available server. I have my markmccracken.net domain hosted primarily for email and this blog, and it does allow HTML-serving, but no server-side scripting like PHP. So that means all the authentication work has to be done in client-side scripting like JavaScript.

The beautiful and media-rich page I whipped up to accomplish the authentication is here. I've had spotty results using this from IE, but it seems pretty reliable under Chrome and Firefox (presuming you have JavaScript turned on, of course). Including the authentication, this page accomplishes a few one-time tasks:

1. Authenticate, as mentioned, getting an access token I can use indefinitely.
2. Search the user's lists on foursquare for one called "My Favorites".
3. Iterate all the venues in that list, putting them and some other helpful defaults into a text box that can be copy/pasted to prime a configuration file.

I like having my long-running scripts talk to me via IRC, because I can passively monitor them from anywhere, and even interact with them in a rudimentary manner. For this project, I used Bot::BasicBot from CPAN, which I've used before to hook a Perl script up to IRC. It's a nice Perl library in the form of a base class where most of the interaction is done in an event-driven manner via the use of callbacks. The two main callbacks for my purposes are tick() and said(). tick() gets called when a timer expires, and said() gets called whenever anyone says anything on the IRC channel. With a little state management and content filtering/parsing, the bot can do pretty much whatever it needs to do with these two callbacks. It can also speak onto the IRC channel by using the say() method.

CPAN is far less scary than The FoursquareTM Site

The only thing left is the meat of the task, which is to check myself into a foursquare venue, wait for a while, and then repeat on the next venue. Since all the venues are pre-loaded into the configuration file, the Perl script just has to iterate them at extremely low speed (one checkin an hour) and make a POST request for each one that actually accomplishes the checkin. For that request, I used the HTTP::Tiny package, because it's usually pre-installed and is very easy to use. Since foursquare requires that POST request to be over https, the IO::Socket::SSL package must also be available.

If you want to try this thing yourself, follow the instructions below for your operating system. I actually have Windows instructions this time because I helped some POWs (Prisoners Of Windows) get it working in their cells. Either way before you begin, create a list on your foursquare account called "My Favorites" and put into it whatever venues you want to automatically check into.

Linux
Perl is probably already installed, but you'll probably need some or all of the extra packages. The cpan utility comes with Perl (at least on Arch), so use it to install the required packages.

sudo pacman -S cpan
cpan Bot::BasicBot
cpan HTTP::Tiny # probably unnecessary
cpan IO::Socket::SSL

Next get the perl script here, and save it somewhere convenient. Give yourself execution permissions.

chmod u+x foursquare_irc.pl

Go to the media-rich and highly advanced authentication page mentioned earlier, and get your configuration starter. Copy it from the web page and paste it into a text file such as foursquare.cfg. Then jump down to the IRC-specific settings described after I repeat these instructions to those Winlozers in small simple words.

Windows

Since you are trapped in Windows, you have no Perl pre-installed. So first, go get Strawberry Perl. Be sure to get the right architecture for your machine: 32-bit or 64-bit. If you're not sure which one you have, then you probably don't want to go any farther with this project anyway. Strawberry Perl was written for Windows users, so it chooses bloat over customization. That means you don't need to install any of those packages I mentioned earlier, because Strawberry Perl pre-installs all of them for you. And yes, that strawberry on their home page is HUGE.

Next get the perl script here, and save it somewhere convenient that you can find again, like your Desktop. In the same place, create an empty text file such as foursquare.txt. In that file, paste the contents of the text box on the media-rich and highly advanced authentication page mentioned earlier. Add the IRC-specific settings described below after I insult some Mac people.

Mac
Go away.

IRC Settings
The highly advanced and media-rich webpage doesn't talk about IRC settings, because there is another version of this script for IRC-impaired people that doesn't use IRC, and I didn't want to confuse them with excess settings. So you'll need to manually add the following settings. Note that none of the stuff in parentheses is real - you have to come up with your own.


IRCChannel= (your IRC channel here, such as #RiskOfRuin)
IRCServer= (your IRC server here, such as irc.foonetic.net)
IRCPort=6667 (probably right, check your server)
IRCNick= (a probably-unique nickname for this script, such as oexkubhtn234)
IRCBoss= (YOUR nick on IRC - the bot only takes orders from this nick)

Run That Sucker

With all the settings in place, go connect your own nick to the IRC channel. Then execute the script:

(Linux) ./foursquare_irc.pl foursquare.cfg

(Windows) .\foursquare_irc.pl foursquare.txt

Yes, Windows people, you're going to need to open a command window. Sorry.

If you've configured everything correctly, you'll see the bot connect to your IRC channel and report its readiness. To interact with it, precede your command with its nick: oexkubhtn234 quit. Simple. It responds to the following commands:

• quit - quits.
• start - starts at first venue after waiting [0 .. MaxSlop] minutes.
• start n - starts at nth venue.
• status - tells you what it's up to in case you forgot.
• settings - reports its settings and venues.

Please use this script responsibly!