Places API roundup (Foursquare v2)

Image from Foursquare Developer Portal

With 800-pound gorillas moving into the LBS ecosystem, location based social networks are fighting for survival in the post check in era. To remain relevant, one approach is to grow the user base organically faster than other social/information networks. This can be achieved by adding quickly more viral features in the native applications and web sites. The number of features and update frequency is directly related to the size the staff. Although small teams can achieve significant results and attract many users, it is a risky business. A safer approach is to attract applications and their developers on the core service API and leverage them. The developers become the innovative lifeblood to bring in more users, it unlocks the staff size limit, brings more features built on the service and mitigates the innovation risk. The approach works as long as the API offers more services than the 800-pound gorilla. In the last few weeks, Foursquare introduced a newer version of its API to attract more users with more developers Dec 9th Foursquare Announcement

Foursquare API v2

Version 1 of the API (v1) – now deprecated – provided few services available in the native Foursquare application. The version 2 (v2) is a major overhaul giving access to most features, improving performance, and dropping the verbose XML output and parsing for more lightweight REST output. In v2, the main API entry point such as users, checkins, venue, tips remain, with photo and comments added, and newly todo for tips. The big difference is a more granular API at the entry point level. A great addition is the API explorer, something that Facebook and Twitter already offered in their own way.

Users

In v2, the users node provides search, aspects (badges, checkins, friends, tips, todos, venuehistory) and actions (request, unfriend, approve, deny, settings). This is major departure from the user API available in version 1 that used to return everything. Friends who used to be available as top node are now rolled into the users.

Venues

v2 of the Venues node brings some nice additions such as the Accuracy of the users location (lat,lon,alt) and the grouping of location field into an array. An experimental herenow Aspect provides a quick overview of the venue with user count additional users information.

Checkins

Instead of providing a checkins and checkin node for read (recent) and write (add), the API now provides two distinct calls for recent and add under a single checkins node. Another change include the ability to comment on a checkin.

Conclusion

No doubts that companies like Twitter and Facebook will provide similar capabilities over time, but there are in no need to rush as just a few are experimenting with location services. While Foursquare has to rely on speed and third parties to mitigate its innovation risk, the 800-pound gorillas don’t need to. They can rely on their small team to bring what’s really important when appropriate, and leverage the scale of their user base to succeed. Game on!

-Olivier

Places API roundup

Image from Good APIs Project Blog

Like a good soufflé, Places API were served new or updated when check ins were hot.

Now that the soufflé has collapsed a bit, let’s taste Places API of services with check in capabilities including Facebook, Foursquare, Google, Gowalla, TellMeWhere, Twitter, and Yelp available to developers.

Facebook

Announced in August 2010 and updated just last week, Facebook Places API is a check in API with search capabilities.

Designed as an extension of the Graph API with a new checkin object, the learning curve is minimal for developers who have already used the Facebook Graph API before. You can tag (i.e. link) a user with a place and query check ins for a Place (i.e Facebook page) or User. The Graph API provides new search capabilities to return Places based on latitude and longitude.

//Retrieve information about a check in
GET https://graph.facebook.com/[checkin_id]

//Retrieve checkins for a user or a page
GET https://graph.facebook.com/[user id]/checkins
GET https://graph.facebook.com/[page id]/checkins

//Search the graph for places page based on coordinates
GET https://graph.facebook.com/search?q=pizza&type=place&center=lat,long&distance=1000


The API being few weeks old, the ability to tag places with more objects from the graph such as photos would be natural.

Foursquare

Like everyone else, Foursquare comes with a very standard based API supporting OAuth, REST, JSON/XML.

In addition to the social features for users and friends, the API features “checkins” to query check ins for a user (i.e. a friend) with a specific location and “checkin” to check a user into a place (i.e. a venue). Places or “venue” can be added, edited, flagged (closed, mislocated, duplicated). “tip” associated with a venue by a user have their own methods.


//query to find out about recent check ins for friends
URL: http://api.foursquare.com/v1/checkins

//request to check a user into a venue
URL: http://api.foursquare.com/v1/checkin

//venue information
URL: http://api.foursquare.com/v1/venue


The API also provides a hierarchy of categories and subcategories for venues.

Google

In developer preview mode (i.e private beta), the API is a database of Places without check in capabilities available publicly just yet, but Google is already working with selected partners including SCVNGR and Booyah who use check ins.

//Places Search
URL: https://maps.googleapis.com/maps/api/place/search/output?parameters
//Place Details
URL: https://maps.googleapis.com/maps/api/place/details/output?parameters

//Place Reports
URL: https://maps.googleapis.com/maps/api/place/report/output?parameters


The API also provides the ability to edit a place with the “report” method.

Gowalla

Reflecting the unique features of its application with Items, Trips, Events, the API has a lot of similarities with Foursquare and Facebook by providing core social features and places in a standard way with REST, JSON, OAuth.

Places are known as “Spots” in the Gowalla terminology. They can be searched by location. Checkins are read-only and can only be queried to retrieve detailed information.


//Query the spots based on location and radius
URL: http://api.gowalla.com/spots?lat=30.2697&lng=-97.7494&radius=50
//Retrieve the details about a checkins
URL: http://api.gowalla.com/checkins/14223232


TellMeWhere

Review service of Places with check in, the API lets developers search for Places and associated content that is ranked by its community of users. For the time being, the API does not provide social features or check in capabilities.

//Search Places by location (rectangle of coordinates)
URL: http://api.tellmewhere.com/v1/searchplaces?rect=48.9,2.34,48.7,2.36&cat=restaurants
//Get Place reviews
URL: http://api.tellmewhere.com/v1/getplacereviews?placeid=zn4AHc

Twitter

Adding more context to a tweet is key to understand Twitter approach to Places. It does not provide a check in API or a Places API for developing LBS Applications, but rather offers a way to tie a location to a tweet from a third party application. The ability to query tweets per Places is not about check in, it is about real time information at the place. However, tweeting at a place is similar

Nevertheless the ability to publish a tweet with a location is a feature available in most LBS Applications today and Twitter came up with a unique guideline just for that. The Twitter Places API is known as “Geo”.

//Tweet with location
URL: http://api.twitter.com/1/statuses/update.xml?status=hello&lat=37.7821120598956&long=-122.400612831116
//Tweet with Place ID
URL: http://api.twitter.com/1/statuses/update.xml?status=hello&place_id=df51dec6f4ee2b2c

//Retrieve a Place ID by name with the Geo API
URL: http://api.twitter.com/1/geo/place.json?name=Twitter%20HQ

Yelp

Review site with check ins capabilities, Yelp offers an API to find Places within a neighborhood with geocoding or location. Although you can check in within the application, this feature is not available thru the API.

//Search of Places within a neighborhood
URL: http://api.yelp.com/neighborhood_search?lat=37.788022&long=-122.399797&ywsid=XXXXXXXXXXXXXXXXXX
//Retrieve reviews for a location
http://api.yelp.com/business_review_search?term=yelp&tl_lat=37.9&tl_long=-122.5&br_lat=37.788022&br_long=-122.399797&limit=3&ywsid=XXXXXXXXXXXXXXXXXX


Summary

There are lots of factors not discussed here that a developer should pay attention to before choosing a Places API, such as query rate limitation, duplication of Places, curated content by the community or business that claim the Place.

Places API have made a huge step forward from their POI database ancestor, and a lot more is yet to come.

Location without Context is irrelevant

Facebook Places launched few weeks ago in the US. Needless to say that the overdue “check in” feature came at the paramount of the frenzy. The storm passed and we don’t hear so much about check in anymore … What happened?

Location as Places, Places as Tags to a Message

I often say “Location without context is irrelevant”. What I mean is that the context (message) is the most pertinent information, location is peripheral, it is an add-on, an additional piece of information associated with the context. When Twitter added Location and Places support in its platform, Twitter added the ability to attach coordinates information to the tweet, and aggregated nearby coordinates into a Place. Facebook did just that, in its own words by adding Checkin to the graph as a new Object with a message, coordinates and a Place.

Places Page and Pivot Table

For those of you familiar with Pivot Table , knowing what is happening at a Place is the same as doing a pivot table on checkin around Location. It becomes easy to find how many checkin happened at certain time or finding out who are the people who checked in. In the #newtwitter, tweets are pivoted around location and show the most recent ones in the new right side details column. Facebook Places Page provide the same experience with friends and status.

The API

As discussed in my previous post about the Open Graph, Facebook provides a great API to access and feed its graph. Here is a quick list of available API, more available on the Facebook documentation:

• You can search for and read users’ check-ins made with Places and Places-enabled applications.
• Every check-in is associated with a check-in ID that represents an object in the Facebook Graph. Check-ins are associated with locations represented by Facebook Pages. The location must have a Facebook Page ID, whether the Page was created on Facebook directly or using the Open Graph protocol.

Permissions

To get a user’s check-ins, request the user_checkins extended permission.
To see the user’s friends’ check-ins, request the friends_checkins extended permission.

Open Graph API

You can GET individual check-ins by passing the check-in ID:

GET https://graph.facebook.com/[checkin_id]

Or you can GET check-in information from individual places, or users:

GET https://graph.facebook.com/[user id]/checkins
GET https://graph.facebook.com/[place page id]/checkins

You can search for recent check-ins for an authorized user and his or her friends:

GET https://graph.facebook.com/search?type=checkin&access_token=ACCESS_TOKEN


What’s next

First Facebook introduced friends tagging in photos and videos. Then Facebook added friends tagging in status. Now you can tag friends in Places. It should not take long before a photo can be tagged automatically with Places based on its meta information in the EXIF. Then pivoting from People-centric stream to Place-centric stream (Place page) would provide a greater experience. The beauty of the Open Graph is the ability to link (i.e. Tag) objects such as posts, checkin, people between them. The possibilities are endless.

Conclusion

So what happened? The Facebook Places release happened without a glitch. The checkin storm passed over and is long way gone. As the feature matures, I see more and more Facebook status tagged with Location, less people concerned about Location in Twitter, and less Foursquare checkin from their power users.

In the end, what is more important is the Context (Status or Tweet) with location as a major artifact for a different perspective. The location for the sake of Location without context, irrelevant.

-Olivier

I <3 Places

In my last blog post, I wrote how easy Places page on the web can participate in the Open Graph. As sites have embraced the initiative, you can “Like” a Place page with a simple click, it then shows up in your friends stream, and the link track back to the original web site hosting the Place page.

What does it mean to “Like” a Place Page?

Actually, you do not “Like” a Place, you “Like” the information about the Place on the page, whether it is meticulously captured by fields agents collecting and updating the information as fast as possible (e.g. InfoUSA, WCities) or whether it is user generated (e.g Foursquare, Yelp). If you “Like” the Yelp page, you enjoy the recommendations, if you “Like” the Foursquare page, you enjoy the mayor special and people who check-in in that place. The value of the page is the unique information associated with the location: the context. The location is a commodity, it is only one way to identify the business uniquely.

Places mashup will be next

With the proliferation of services surrounding Places, mashup will be next. In a recent TechCrunch article, Eric Schonfeld asked for an Open Database Of Places, a super store that would contain everything about a Place. In other word a beast, inevitably requiring some sort of policy around it, quickly unmanageable. Good luck with that. This approach is certainly not the preferred way as it was also echoed on opengeodata.org.

So what is the solution for Place Information Aggregation? First, duplication of Places need to be fixed within each content provider. If Foursquare has few Places for the same Location, a local business who want to advertise will ask for one of the duplicate to be removed. Luckily Placecast MatchAPI provides an easy way to identify duplicates for data clean up, free of charge. Across multiple sites, duplication is not an issue, as each content provider brings its own meal to the table. To achieve automatic aggregation, programmers just need a service that returns the ID or URI of a Place from a provider by submitting a set of coordinates. When this service is trusted as a commons tool, every content provider will want to get on board to share their Place ID for a physical location.

Who is up for it?

-Olivier

Open Graph and Places

Few weeks ago, Facebook introduced the Open Graph initiative, a major step to make the web a lot smarter with semantic, by connecting sites together with more information than hyperlinks. To participate with your own site, add few tags on every page, and you are in business! From there, there is no limits to widespread your own Open Graph, your page can be referenced on other sites with a name, image, URL and additional information like a physical Location, an address or coordinates.

At launch, Yelp embraced the initiative to promote its pages, and now WCities, Where, and Foursquare have already updated their Places page. On these sites, you can “Like” a place or post information in your Facebook stream with the help of the Facebook widgets.

How to participate in the Open Graph

To bring a web page into the Open Graph ecosystem, you must include mandatory meta information with the following Open Graph tag:

og:title - The title of your object as it should appear within the graph, e.g., "Market Bar".
og:type - The type of your object, e.g., "restaurant". Depending on the type you specify, other properties may also be required.
og:image - An image URL which should represent your object within the graph.
og:url - The canonical URL of your object that will be used as its permanent ID within the graph.


Adding a location with coordinates is optional but possible

og:latitude - e.g., "37.795466".
og:longitude - e.g., "-122.393779"

For an address, you can include the following tags

og:street-address - e.g., "One Ferry Building"
og:locality - e.g, "San Francisco"
og:region - e.g., "CA"
og:postal-code e.g., "94111"
og:country-name - e.g., "USA"


For example, a Market Bar page served by WCities may have the following information

<html xmlns:og="http://opengraphprotocol.org/schema/">
<head>
...
<meta property="og:title" content="Market Bar" />
<meta property="og:type"  content"restaurant" />
<meta property="og:image" content="http://content.wcities.com/images/cityrecords/low_resolution/323189.jpg" />
<meta property="og:url" content="http://wcities.com/san-francisco/restaurants/poi-marketbar-323189.html" />

<meta property="og:latitude" content="37.795466" />
<meta property="og:longitude" content="-122.393779" />
<meta property="og:street-address" content="1 Ferry Building" />
<meta property="og:locality" content="San Francisco" />
<meta property="og:region" content="CA" />
<meta property="og:postal-code" content="94111" />
<meta property="og:country-name" content="USA" />

</head>

If you need to test your page implementation of the Open Graph tags, try the following link with your page URL: http://www.opengraph.in/

At this point, your page can be consumed and linked back by any site. Interestingly Facebook recommends web sites to participate in the Open Graph but does not implement it yet on its web pages. As of today, the only access to Facebook Open Graph is thru the API.

Social Graph and Social Plugins

Facebook manages a “Social” Graph, a site that connects people and interests altogether. The more sites that embrace the Open Graph, the more people will be able to share on Facebook. Like a song on Pandora, a movie on imdb, Places are important in the overall social experience and no wonder why many companies have added the meta tags in their pages.

At launch, Facebook provided a series of social plugins or widgets. Their role is to simplify the consumption of any Open Graph web pages by its platform, one of them being the famous “Like” button. Every time a Facebook user clicks on the link, Facebook updates its own counter for that page. In other words, Facebook crowd source the index of the web, an invaluable information to provide tailored search results back to its users.

Other Facebook plugins include people recommendations for that page or facepile gallery. In short, the Facebook plugins let you add a Social dimension to your site in a snap while feeding the platform back with information.

What is Your Graph

Every company manages its own graph of information, with public and private information. An airline for instance offers flights between destinations using planes. Destinations, Flights and Planes are public knowledge that could be accessible thru the airline Open Graph. Coupled with a social graph, users could comment on a flight and find which friends are on it. So every company should start thinking about its own and very unique Graph.

Spread Your Graph with Plugins

Facebook took the lead in the Open Graph by driving a major initiative beyond its own social graph. Plugins have become essential to widespread the graph beyond the web and mobile properties.

So it is a matter of time before we see new plugins show up to make consumption of all sorts of Graph a lot easier.

What will be yours?

-Olivier