Those who know me, can attest that I'm a early adopter when it comes to social networking systems.  The latest one I've been getting into lately is FourSquare.com. 

FourSquare.com describes itself as 50% friend finder, 30% social city guide, and 20% nightlife game.  They include ways to keep up with what your friends are doing as well as offering up some fun challenges to have you explore cities in different ways.

Once I've played around with a social networking site for a bit, my next step is to see what kind of API's they have exposed and see if I can build my own app to integrate with the site.  It turns out that the FourSquare.com has exposed a public API in their FourSquare-API Google Group.

So, as I did with my Posh-Tweet, Posh-Bing, Posh-TwitPic, and Posh-Delicious libraries, I went ahead and wrote a PowerShell library of functions to access the FourSquare APIs.

The API is broken down into these categories:

Credentials

• Get-FourSquare.Credentials - Get the credentials for your FourSquare.com account.
• Set-FourSquare.Credentials - Set the credentials for your FourSquare.com account.

GEO Methods

• Get-FourSquare.Citites - Returns a list of currently active cities.
• Check-FourSquare.City - When given a lat/long, returns the closest foursquare city.
• Switch-FourSquare.City - When given a valid foursquare cityid, changes the user's default city.
• Get-FourSquare.Checkins - Returns a list of recent checkins from friends.
• New-FourSquare.Checkin - Allows you to check-in to a place.
• Get-FourSquare.History - Returns a history of checkins for the authenticated user (across all cities).

User Methods

• Get-FourSquare.User - Returns profile information (badges, etc) for a given user.
• Get-FourSquare.Friends - Returns a list of the authenticated user's friends.
• Get-FourSquare.Venues - Returns a list of venues near the area specified or that match the search term.
• Get-FourSquare.Venue - Returns venue data, including mayorship, tips/to-dos and tags
• Add-FourSquare.Venue - Allows you to add a new venue.

Tip Methods

• Get-FourSquare.Tips - Returns a list of tips near the area specified.
• Add-FourSquare.Tip - Allows you to add a new tip or to-do at a venue.

Other Methods

• Get-FourSquare.Status - Returns the string "ok".

Usage:

To use the API's you must first register on FourSquare.com.  The username and password you use to create the account will be used in this API with the Set-FourSquare.Credentials method.  After setting your credentials, you can call any of the other methods and start updating your status from the comfort of your PowerShell prompt.  The following example will register the functions in the current runspace, set the credentials, query the available citites, and then checkin at the Cafe next door for lunch.

PS C:\> . .\Posh-FourSquare.ps1
PS C:\> Set-FourSquare.Credentials -user myuser -pass mypass
PS C:\> Get-FourSquare.Cities | Format-Table
id   timezone                name                    geolat                  geolong
--   --------                ----                    ------                  -------
56   Europe/Amsterdam        Amsterdam               52.3789                 4.90067
46   America/New_York        Atlanta                 33.7525                 -84.3888
42   America/Chicago         Austin                  30.2669                 -97.7428
58   America/Denver          Black Rock City         40.7693                 -119.22
24   America/New_York        Boston                  42.3583                 -71.0603
32   America/Chicago         Chicago                 41.8858                 -87.6181
43   America/Chicago         Dallas / Fort Worth     32.7887                 -96.7676
25   America/Denver          Denver                  39.734                  -105.026
47   America/New_York        Detroit                 42.3333                 -83.0484
48   America/Chicago         Houston                 29.7594                 -95.3594
49   America/Los_Angeles     Las Vegas               36.1721                 -115.122
34   America/Los_Angeles     Los Angeles             34.0443                 -118.251
39   America/New_York        Miami                   25.7323                 -80.2436
51   America/Chicago         Minneapolis / St. Paul  44.9609                 -93.2642
22   America/New_York        New York City           40.7255                 -73.9983
33   America/New_York        Philadelphia            39.8694                 -75.2731
53   America/Phoenix         Phoenix                 33.4483                 -112.073
37   America/Los_Angeles     Portland                45.527                  -122.685
38   America/Los_Angeles     San Diego               32.7153                 -117.156
23   America/Los_Angeles     San Francisco           37.7587                 -122.433
41   America/Los_Angeles     Seattle                 47.6036                 -122.326
59   America/Vancouver       Vancouver               49.259515               -123.103867
31   America/New_York        Washington, DC          38.8964                 -77.0447
PS C:\> New-FourSquare.Checkin -venue "Urban Cafe" -shout "It's lunch time!"
message : OK! We've got you @ Urban Cafe.  This is your 4th checkin here!
id      : 1398385
created : Mon, 05 Oct 09 12:50:00 +0000
venue   : venue
mayor   : mayor

Get The Source

The full source for the script is available from my blog at Posh-FourSquare.ps1

Enjoy!

-Joe