PoshFourSquare_thumb[2]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-Tableid timezone name geolat geolong-- -------- ---- ------ -------56 Europe/Amsterdam Amsterdam 52.3789 4.9006746 America/New_York Atlanta 33.7525 -84.388842 America/Chicago Austin 30.2669 -97.742858 America/Denver Black Rock City 40.7693 -119.2224 America/New_York Boston 42.3583 -71.060332 America/Chicago Chicago 41.8858 -87.618143 America/Chicago Dallas / Fort Worth 32.7887 -96.767625 America/Denver Denver 39.734 -105.02647 America/New_York Detroit 42.3333 -83.048448 America/Chicago Houston 29.7594 -95.359449 America/Los_Angeles Las Vegas 36.1721 -115.12234 America/Los_Angeles Los Angeles 34.0443 -118.25139 America/New_York Miami 25.7323 -80.243651 America/Chicago Minneapolis / St. Paul 44.9609 -93.264222 America/New_York New York City 40.7255 -73.998333 America/New_York Philadelphia 39.8694 -75.273153 America/Phoenix Phoenix 33.4483 -112.07337 America/Los_Angeles Portland 45.527 -122.68538 America/Los_Angeles San Diego 32.7153 -117.15623 America/Los_Angeles San Francisco 37.7587 -122.43341 America/Los_Angeles Seattle 47.6036 -122.32659 America/Vancouver Vancouver 49.259515 -123.10386731 America/New_York Washington, DC 38.8964 -77.0447PS 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 : 1398385created : Mon, 05 Oct 09 12:50:00 +0000venue : venuemayor : mayor

Get The Source

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

Enjoy!

-Joe