= 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
== 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 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 (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.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 => '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", @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">
=== 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
Tags can also be accessed through their spot, either by calling the model's cached tag_list, branded_tags, or making an API request for a full tag listing.
spot = Whatser.client.spots.find( spot_id )
spot.tag_list
spot.branded_tags
spot.tags
In addition to user tags, some spots will also have branded tags, keywords promoted by Whatser partners and associated with branded images; for normal user tags, these image urls are not used. The images are customized for three platforms (web, touch, and wap), and two sizes (list and detail).
<Whatser::Tag @name="my tag", @poi_id=101, @web_list_pic="http://wht.sr/1.png", @web_detail_pic="http://wht.sr/2.png", @touch_list_pic="http://wht.sr/3.png", @touch_detail_pic="http://wht.sr/4.png", @wap_list_pic="http://wht.sr/5.png", @wap_detail_pic="http://wht.sr/6.png">
=== 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">
=== 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, 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
== Copyright
Copyright (c) 2010-2011 Travis Dunn / SoGeo Company. See LICENSE.txt for further details.
FAQs
Unknown package
We found that whatser demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.
Research
Security News
A threat actor's playbook for exploiting the npm ecosystem was exposed on the dark web, detailing how to build a blockchain-powered botnet.
Security News
NVD’s backlog surpasses 20,000 CVEs as analysis slows and NIST announces new system updates to address ongoing delays.