= Whatser Gem

The 'Whatser API' Gem is a simple Ruby / Rails wrapper for interacting with Whatser's location-based web services (see http://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, reviews, check ins, etc.)
* user spot collection management
* 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 (https://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 (https://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 => "git@github.com:sogeo/whatser"

And instantiate a Whatser client as need:

    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 (http://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.user.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 => 'first@example.com;second@example.com;third@example.com' )
    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="user@example.com", @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">

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

    <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">


=== 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">


=== Reviews

A review is a short- to long-form text article about a spot.

    Whatser.client.reviews.list( spot_id, :page => 1, :per_page => 10 )
    Whatser.client.reviews.find( spot_id, review_id )
    Whatser.client.reviews.create( spot_id, :body => 'my spot review.' )
    Whatser.client.reviews.delete( spot_id, review_id )
    m = Whatser.client.reviews.new( :body => 'my spot review.' )
    m.save
    m.delete

    <Whatser::Review @user_id=null, @id=101, @body="whatser spot review.", @created_at="2010-12-24T16:45:55Z">


=== Details

Details are miscellaneous, freeform information about a spot, such as operating hours, pricing, etc. The data attribute serializes a hash, which can be used to store arbitrary spot details.

    Whatser.client.details.list( spot_id, :page => 1, :per_page => 10 )
    Whatser.client.details.find( spot_id, details_id )
    Whatser.client.details.create( spot_id, :data => {:title => 'details', :opening_hours => '8:00-5:00'} )
    Whatser.client.details.delete( spot_id, review_id )
    m = Whatser.client.details.new( :data => {:title => 'details', :opening_hours => '8:00-5:00'} )
    m.save
    m.delete

    <Whatser::Detail @data={"meta"=>"Long metadata here", "opening_hours" => "9-5"}, @user_id=null, @id=101>


=== 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">


=== Tags

Tags are freeform text that reflect user thoughts, opinions, and feedback on specific spots.

    Whatser.client.tags.list( spot_id )
    Whatser.client.tags.create( spot_id, 'my tag' )
    Whatser.client.tags.delete( spot_id, 'my tag' )
    m = Whatser.client.tags.new( :name => 'my tag' )
    m.save
    m.delete

    <Whatser::Tag @name="my tag">


=== 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", @premium=false, @avatar_pic="http://example.com/avatars/thumb/1.jpg", @promoted=false, @name="Example User", @id=1>


=== 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>


=== Data Sources

A data source represents a free or purchasable content stream of collected spots, media, and reviews. Users can subscribe to data sources in order to access their content in Whatser. To begin the subscription and payment process, redirect your user to the data source's subscription_url.

    Whatser.client.data_sources.list( :page => 1, :per_page => 10 )
    Whatser.client.data_sources.for_users( :user_id => [101,23], :page => 1, :per_page => 10 )
    m = Whatser.client.data_sources.find( 1 )
    redirect_to m.subscription_url(:display => 'touch')

    <Whatser::DataSource @review_count=405, @poi_count=0, @price=0.0, @collection_count=0, @name="Rough Guides - Barcelona", @media_count=0, @id=9, @users=[{"name": "premium user", "id": 33}]>


=== 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, or globally.

    Whatser.client.feed.user( user_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">


=== Social Networks

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 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

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: travis@sogeocompany.com
* API Documentation: http://docs.sogeoapi.com
* Facebook: http://www.facebook.com/sogeo
* Whatser: http://www.whatser.com
* Twitter: @sogeoapi

== Copyright

Copyright (c) 2010 Travis Dunn / SoGeo Company. See LICENSE.txt for
further details.