I’ve been working with the Foursquare API over the past several months and I can say v2 of the API is a dramatic improvement from the previous incarnation. Probably the biggest advancement is the switch to oAuth2. Anyone who has worked with oAuth will tell you the original protocol’s authentication scheme was a real pain to work with. oAuth2 gets the same work done in half the steps–very streamlined.

Although, it seems one thing Foursquare has been missing from the start is a geocoding API. As it stands now, the only way to search for a location in Foursquare is by latitude and longitude using the search API endpoint.

The documentation for the search API call is here. But note that it’s actually semi-incorrect. Although it claims you can search unauthenticated, you need to pass along your API key and secret like so:

https://api.foursquare.com/v2/venues/search?ll=lat,lng&client_id=xxx&client_secret=xxx

Where client_id is your API key and client_secret is your secret as displayed on the oAuth consumer management page.

So how do you search by address? In short, you can’t. You have to get the latitude and longitude of the address via geocoding. This is a service Foursquare does not provide. Luckily, there are tons of geocoding APIs out there. Most are free to use, but many require premium accounts if you are going to make a lot of calls to it.

In my case, first I make a call to the Google Maps geocoding API like so:

http://maps.googleapis.com/maps/api/geocode/json?address=xxx&sensor=false

Where xxx is a urlencoded string containing the address. It returns a JSON object with the latitude and longitude of the address (among other things). Then I pass this to the Foursquare search endpoint to pick out its location in their database.

Not too difficult, but it would be nice if Foursquare had their own geocoding solution so you could pass a street address to the search API call as an alternative. Keep it all in the family.

I will say the best thing about the search API is that it is unauthenticated. You can use it as a general database of places without having a user account. As far as I know, Facebook Places requires you to be logged in to search their database and access the API. Foursquare is a good solution for apps that need a general places database–in much the same way you might use CityGrid or Bing’s places feature.