Whatser Gem

The ‘Whatser API’ Gem is a simple Ruby / Rails wrapper for interacting with Whatser’s location-based web services (see docs.sogeoapi.com for more details).

Overview

read/write API access
OAuth 2 authentication (using oauth2)
network connectivity (using httparty)
simple DSL for API resource classes (spots, media, comments, check ins, etc.)
user spot collection management
check-in aggregation
social network integration (facebook, twitter, foursquare, gowalla)
photo uploads

Usage

0. Register your application with the Whatser API

In order to use the Whatser Gem, you’ll need to register for a Whatser user account (production-2.sogeoapi.com/oauth/user/new), and create a client application for that user which will then give you an application key and secret (production-2.sogeoapi.com/oauth/user/client_applications/new).

Once you have your key and secret, you can start using the gem by instantiating a Whatser client with those credentials:

1. Instantiate a Client (on demand or with default configuration)

Declare Whatser in your Gemfile:

gem 'whatser', :git => "[email protected]:sogeo/whatser"

And instantiate a Whatser client as needed:

client = Whatser::Client.new(:api_key => 'key', :api_secret => 'secret', :oauth_token => '123abc', :logger => Rails.logger)

or…

Whatser::Client.configure do |config|
  config.api_key = 'key'
  config.api_secret = 'secret'
  config.logger = Rails.logger
end
client1 = Whatser::Client.new( :oauth_token => '123abc' )
client2 = Whatser::Client.new( :oauth_token => '789xyz' )

2. Authenticate a User

Nearly every API call must be performed in the context of a user, and users authenticate with the API by using an oauth token.

If you don’t already have an oauth token for your user, you can get one by following the standard OAuth 2 web server flow (tools.ietf.org/html/draft-ietf-oauth-v2-10).

First, redirect your user to the Whatser website where they will be presented with a login screen and a dialog to authorize your application to access their Whatser account. In a Rails controller, the command would likely look as follows. e.g.

redirect_to Whatser.client.oauth_authorize_url( :redirect_uri => 'https://example.com/callback' )

Second, you’ll need a controller action on your web app to which the Whatser API will redirect the user after they complete the authorization process. Within this action, you’ll need to capture the access token parameter and use to obtain a user oauth token, after which the authorization will be complete, and you may begin accessing the API with your user. e.g.

def oauth_callback
  code = params[:access_token]
  session[:oauth_token] = Whatser.client.get_oauth_token(code, :redirect_uri => 'https://example.com/callback').token
end

Note, you should store your user’s oauth token so it can be used to instantiate Whatser client sessions as needed.

3. Access the API

Once you have an oauth token for a user, you can access the Whatser API by instantiating a Whatser client and making calls using the Whatser resource classes. e.g.

client = Whatser::Client.new( :oauth_token => '123abc' )
client.authorized?
authenticated_user = client.users.me
spots = client.spots.search(:geo => "52.3665312,4.8931739", :text => "pizza", :per_page => 30).data
spots.each { |spot| spot.tag('my tag') }
a_spot = client.spots.find(12345).data
my_spot = client.spots.create(:name => 'work', :street => 'main street', 'city' => 'metropolis').data
new_spot = client.spots.new(:name => 'work', :street => 'main street', 'city' => 'metropolis')
new_spot.save
new_spot.delete

Responses from the API are wrapped in the Whatser::Response class, allowing you to inspect the detailed results of your API requests, e.g.

client = Whatser::Client.new( :oauth_token => '123abc' )
results = client.spots.search(:geo => "52.3665312,4.8931739", :text => "pizza", :per_page => 30)
results.http_status
results.error.blank?
results.error_description
results.data

You can use the Response helpers to easily inspect your the result of your request.

if results.succeeded?
elsif results.unauthorized?
elsif results.forbidden?
elsif results.not_found?
elsif results.not_allowed?
elsif results.not_acceptable?
elsif results.confict?
elsif results.unprocessable_entity?
elsif results.server_error?
end

Resource Guide

Users

The API stores user profiles, which may have originated either directly from API registration, or else by connecting through a social network. In order to access the API on behalf of a user, you’ll need an oauth token representing that user’s credentials.

Whatser.client.users.me
Whatser.client.users.search( :text => 'name or email', :page => 1, :per_page => 10 )
Whatser.client.users.suggested( :page => 1, :per_page => 10 )
Whatser.client.users.invite( :emails => '[email protected];[email protected];[email protected]' )
Whatser.client.users.create( params[:user] )
m = Whatser.client.users.find( user_id )
m.connection

<Whatser::User @bio="Example", @location="Amsterdam, NL", @facebook_id="1234567890", @email="[email protected]", @gowalla_id="1234567890", @avatar_pic="http://example.com/img/14.jpg", @promoted=false, @name="User", @twitter_name="example", @last_login_at="2010-12-24T16:46:23Z", @twitter_id="1234567890", @id=101, @foursquare_id="1234567890", @thanks_count=0, @poi_count=0, @check_ins_count=0, @media_count=0, @taggings_count=0, @follows_count=0, @followers_count=0, @comments_count=0>

The API also permits anonymous user access, but in order to do so an anonymous user must first be created. Anonymous users have limited privileges and no email address, but otherwise function identically to authorized users. After the user is created, you can get the oauth token to use with your client and perform actions on behalf of the anonymous user.

client = Whatser::Client.new
anonymous = client.users.anonymous
client.oauth_token = anonymous.oauth_token
suggested_poi = client.spots.suggested
client.collections.add( suggested_poi.data.first.id )

Spots (Points of Interest)

A spot is a named geographical location and the most fundamental kind of content in the API. Typically with counterparts in Gowalla or Foursquare, spots have various associated content such as photos or tags. If you supply only the lat and lng, or only the address, the spot will be automatically geocoded/reverse geocoded appropriately.

Whatser.client.spots.suggested( :page => 1, :per_page => 10 )
Whatser.client.spots.search( :geo => "52.3665312,4.8931739", :stats => true, :details => true )
Whatser.client.spots.find( spot_id )
Whatser.client.spots.create( :name => 'my spot', :lat => 52.0, :lng => 4.0, :street => '123 st.', :region => 'Noord Holland', :city => 'Amsterdam', :postal_code => '1012', :country => 'Netherlands' )
Whatser.client.spots.delete( spot_id )
m = Whatser.client.spots.new( :name => 'my spot', :lat => 52.0, :lng => 4.0 )
m.save
m.delete
results = m.comments
results = m.tags
results = m.activity

<Whatser::Poi @lng=4.0, @region="Noord Holland", @gowalla_id="123456", @lat=52.0, @tag_list=nil, @city="Amsterdam", @name="Example Spot", @country="Netherlands", @street="example street", @id=101, @postal_code="1012", @foursquare_id="123456", @created_at="2010-12-24T16:46:23Z">

You can also lists of users who have interacted with a spot in some way, either by checking-in or by adding it to their collection. These methods can be called directly from a spot, or by the User class.

users = my_spot.visitors( :page => 1, :per_page => 10 )
users = my_spot.collectors( :page => 1, :per_page => 10 )

users = Whatser.client.users.visitors(spot_id, :page => 1, :per_page => 10 )
users = Whatser.client.users.collectors(spot_id, :page => 1, :per_page => 10 )

Collections

A collection is a set of spots of particular interest to a user. By adding spots to their personal collection, users build a list of their favorite locations around a city.

Whatser.client.collections.mine( :page => 1, :per_page => 10 )
Whatser.client.collections.add( spot_id )

<Whatser::Collection @data=[#<Whatser::Poi>, #<Whatser::Poi>], @city_name="Amsterdam", @city=["Amsterdam"]>

As a convenience you can also iterate over a collection’s spot data:

collection = Whatser::Collection.new( [spot1, spot2, spot3] )
collection.each { |c| puts c.name }

If a user somehow discovers a spot due to another user’s recommendation or similar, you can explicitly thank them for the recommendation, slightly increasing the user’s Whatser reputation and influence as an opinion leader.

user.thanks( spot_id, :message => 'thanks, this spot looks great', :facebook => true, :twitter => true)

Cities

A user’s cities represent the cities in which they have collected spots.

Whatser.client.cities.mine( :page => 1, :per_page => 10 )
Whatser.client.cities.user( user_id, :page => 1, :per_page => 10 )

<Whatser::City @count=5, @name="Amsterdam">

Media

Media are photos, logos, and other graphics associated with a spot. You can create new media either by supplying a file for a multipart upload, or else with a link to an existing online image.

Whatser.client.media.list( spot_id, :page => 1, :per_page => 10 )
Whatser.client.media.find( spot_id, media_id )
Whatser.client.media.delete( spot_id, media_id )
Whatser.client.media.create( spot_id, :remote_resource => 'http://example.com/img/whatser.png' )
m = Whatser.client.media.new( :spot_id => 1, :resource => <File> )
m.save
m.delete

<Whatser::Media @mid_pic="http://example.com/images/medium/4394.jpg", @name="photo.jpg", @small_pic="http://example.com/images/small/4394.jpg", @poi_id=101, @mime="image/jpeg", @thumb_pic="http://example.com/images/thumb/4394.jpg", @user_id=1, @id=33, @url="http://example.com/images/original/4394.jpg", @created_at="2010-12-20T08:25:56Z">

Follows

Follows represent a user’s interest in another user, namely the user’s spot activity, collections, and content. Following another user integrates that user’s Whatser social and POI graph into the follower’s suggestions and other dynamic Whatser content.

Whatser.client.follows.list( :page => 1, :per_page => 10 )
Whatser.client.follows.create( user_id )
Whatser.client.follows.ignore( user_id )
Whatser.client.follows.connection( user_id )
m = Whatser.client.follows.new( params[:user] )
m.save
m.delete

<Whatser::Follow @location="Amsterdam, NL", @avatar_pic="http://example.com/avatars/thumb/1.jpg", @promoted=false, @name="Example User", @id=1>

You can also get a list of a given user’s followers either directly through a user, or the Follow class.

Whatser.client.follows.followers( user_id, :page => 1, :per_page => 10 )
following_users = user.followers( :page => 1, :per_page => 10 )

Check Ins

A check in represents a user’s visit to a spot, and will typically have a counterpart in other location-based applications such as Foursquare, Gowalla, and Facebook Places.

Whatser.client.check_ins.list( :page => 1, :per_page => 10 )
Whatser.client.check_ins.create( spot_id, :lat => 52.3665312, :lng => 4.8931739, :gowalla => true, :foursquare => true, :check_in_at => Time.now - 15.minutes, :check_out_at => Time.now, :rating => 2, :message => 'checked in' )
m = Whatser.check_ins.new( :check_in_at => Time.now )
m.save

<Whatser::CheckIn @message="statuscastin' over here", @lng=4.8931739, @rating=3, @lat=52.3665312, @check_out_at="2010-12-24T16:46:38Z", @name="Popular Spot", @poi_id=101, @check_in_at="2010-12-24T16:31:38Z", @user_id=101>

Comments

A comment is just a short user note that can be associated with other resources. At the moment, you can comment on a POI, Media, or an Activity Feed. Users can also delete their own comments.

Whatser.client.comments.poi( poi_id, :page => 1, :per_page => 10 )
Whatser.client.comments.media( media_id, :page => 1, :per_page => 10 )
Whatser.client.comments.create( 'activity_feed', feed_id, 'This is a comment. Interesting activity!' )
Whatser.client.comments.create( 'media', media_id, 'This is a comment on a media. Stunning photo!' )
m = Whatser.client.comments.create( 'poi', spot_id, 'This is a comment on a spot. Nice spot!' )
m.delete

<Whatser::Comment @body="This is a comment.", @id=101, @user_id=101, @activity_feed_id=null, @user_avatar="http://example.com/images/thumb/4394.jpg", @subject_id=33, @user_name='Whaster User', @created_at="2010-12-24T16:31:38Z", @subject_type='poi', @subject_name="Some Spot">

Activity Feeds

User activity is recorded by the API, for example when a user adds or tags a POI, befriends another user, or uploads a photo. This activity is recorded in a user’s activity feed, a collection of short messages detailing that user’s activity. You can view feeds either by user, by spot, or globally.

Whatser.client.feed.user( user_id, :page => 1, :per_page => 10 )
Whatser.client.feed.spot( spot_id, :page => 1, :per_page => 10 )
Whatser.client.feed.mine( :page => 1, :per_page => 10 )
Whatser.client.feed.global( :page => 1, :per_page => 10 )

<Whatser::ActivityFeed @message="you uploaded a photo.", @poi_id=101, @object_avatar=nil, @user_avatar="http://example.com/avatars/imgs/1.jpg", @user_id=33, @object_name="Something", @user_name="This User", @object_id=1001, @poi_name="Some Spot", @city="Amsterdam">

The API integrates with several social networks (Facebook, Foursquare, Gowalla, and Twitter), allowing users from those networks to login from or connect their accounts with Whatser. All four networks are supported for connecting a user account (via the OAuth 2 web authorization flow), and disconnecting a user account. In addition, the API provides access to other select parts of these networks to support social media and location-based user activity.

To connect a user to or register a new user through their social network, redirect the user to the service’s connection_url. Once the user has been connected their network, they are then redirected through the Whatser authentication path as normal, where you can then retrieve their oauth access token.

redirect_to Whatser.client.facebook.connection_url(:display => ‘wap’) Whatser.client.facebook.disconnection_url redirect_to Whatser.client.foursquare.connection_url(:display => ‘touch’) Whatser.client.foursquare.disconnection_url

redirect_to Whatser.client.gowalla.connection_url(:display => 'web')
Whatser.client.gowalla.disconnection_url
redirect_to Whatser.client.twitter.connection_url(:display => 'touch')
Whatser.client.twitter.disconnection_url

The Twitter and Facebook classes allow for content publishing, meaning status tweets and wall posts, respectively. For Facebook wall posts, supplying one or more user ids to the method will post to the wall of those users (Facebook permissions permitting), while omitting it will post only to the authorized user’s wall by default.

Whatser.client.facebook.wall_post(:name => 'my link', :link => 'http://example.com', :caption => 'click this link', :description => 'summary here', :picture => 'http://example.com/img/whatser.png', :user_id => '101,201,33')
Whatser.client.twitter.status_update('tweeting!', :lat => 52.3665312, :long => 4.8931739, :display_coordinates => true, :place_id => twitter_places_id)

When a user connects a social network account to the Whatser API, their friends are automatically imported at this time. To keep a user’s friends updated, you can call a get_friends method on the Twitter, Foursquare, and Facebook classes to import any new friends of that user who have recently registered with Whatser. Note, only newly imported friends are returned.

Whatser.client.facebook.get_friends
Whatser.client.twitter.get_friends
Whatser.client.foursquare.get_friends

You can use convenience methods on users and spots to determine their connections to external networks.

m = Whatser.client.users.find(1)
m.facebook_connected?
m.foursquare_connected?
m.gowalla_connected?
m.twitter_connected?

m = Whatser.client.spots.find(1)
m.foursquare_connected?
m.gowalla_connected?

Contact

Developer Email: [email protected]
API Documentation: docs.sogeoapi.com
Facebook: www.facebook.com/sogeo
Whatser: www.whatser.com
Twitter: @whatserapi

Whatser Gem

Overview

Usage

0. Register your application with the Whatser API

1. Instantiate a Client (on demand or with default configuration)

2. Authenticate a User

3. Access the API

Resource Guide

Users

Spots (Points of Interest)

Collections

Cities

Media

Tags

Follows

Check Ins

Comments

Activity Feeds

Contact

Copyright

Whatser Gem

Overview

Usage

0. Register your application with the Whatser API

1. Instantiate a Client (on demand or with default configuration)

2. Authenticate a User

3. Access the API

Resource Guide

Users

Spots (Points of Interest)

Collections

Cities

Media

Tags

Follows

Check Ins

Comments

Activity Feeds

Social Networks

Contact

Copyright