instagram_geo 0.8.7

data/Gemfile

@@ -0,0 +1,3 @@
+source "http://rubygems.org"
+
+gemspec

data/LICENSE.md

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Instagram (Burbn, Inc.)
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,144 @@
+The Instagram Ruby Gem
+====================
+A Ruby wrapper for the Instagram REST and Search APIs
+
+
+Installation
+------------
+	gem install instagram
+
+
+Follow @instagramapi on Twitter
+----------------------------
+You should [follow @instagramapi on Twitter](http://twitter.com/#!/instagramapi) for announcements,
+updates, and news about the Instagram gem.
+
+
+Join the mailing list!
+----------------------
+<https://groups.google.com/group/instagram-ruby-gem>
+
+
+Does your project or organization use this gem?
+-----------------------------------------------
+Add it to the [apps](http://github.com/Instagram/instagram-ruby-gem/wiki/apps) wiki!
+
+
+Sample Application
+------------------
+	require "sinatra"
+	require "instagram"
+
+	enable :sessions
+
+	CALLBACK_URL = "http://localhost:4567/oauth/callback"
+
+	Instagram.configure do |config|
+	  config.client_id = "YOUR_CLIENT_ID"
+	  config.client_secret = "YOUR_CLIENT_SECRET"
+	end
+
+	get "/" do
+	  '<a href="/oauth/connect">Connect with Instagram</a>'
+	end
+
+	get "/oauth/connect" do
+	  redirect Instagram.authorize_url(:redirect_uri => CALLBACK_URL)
+	end
+
+	get "/oauth/callback" do
+	  response = Instagram.get_access_token(params[:code], :redirect_uri => CALLBACK_URL)
+	  session[:access_token] = response.access_token
+	  redirect "/feed"
+	end
+
+	get "/feed" do
+	  client = Instagram.client(:access_token => session[:access_token])
+	  user = client.user
+
+	  html = "<h1>#{user.username}'s recent photos</h1>"
+	  for media_item in client.user_recent_media
+	    html << "<img src='#{media_item.images.thumbnail.url}'>"
+	  end
+	  html
+	end
+
+
+API Usage Examples
+------------------
+    require "rubygems"
+    require "instagram"
+
+    # Get a list of a user's most recent media
+    puts Instagram.user_recent_media(777)
+
+    # Get the currently authenticated user's media feed
+    puts Instagram.user_media_feed
+
+    # Get a list of recent media at a given location, in this case, the Instagram office
+    puts Instagram.location_recent_media(514276)
+
+    # All methods require authentication (either by client ID or access token).
+	# To get your Instagram OAuth credentials, register an app at http://instagr.am/oauth/client/register/
+    Instagram.configure do |config|
+      config.client_id = YOUR_CLIENT_KEY
+      config.access_token = YOUR_ACCESS_TOKEN
+    end
+
+    # Get a list of all the users you're following
+    puts Instagram.follows
+
+    # Get a list of media close to a given latitude and longitude
+    puts Instagram.media_search("37.7808851","-122.3948632")
+
+	# Get a list of the overall most popular media items
+	puts Instagram.media_popular
+
+	# Search for users on instagram, by name or username
+	puts Instagram.user_search("shayne sweeney")
+
+
+Contributing
+------------
+In the spirit of [free software](http://www.fsf.org/licensing/essays/free-sw.html), **everyone** is encouraged to help improve this project.
+
+Here are some ways *you* can contribute:
+
+* by using alpha, beta, and prerelease versions
+* by reporting bugs
+* by suggesting new features
+* by writing or editing documentation
+* by writing specifications
+* by writing code (**no patch is too small**: fix typos, add comments, clean up inconsistent whitespace)
+* by refactoring code
+* by closing [issues](http://github.com/Instagram/instagram-ruby-gem/issues)
+* by reviewing patches
+
+
+Submitting an Issue
+-------------------
+We use the [GitHub issue tracker](http://github.com/Instagram/instagram-ruby-gem/issues) to track bugs and
+features. Before submitting a bug report or feature request, check to make sure it hasn't already
+been submitted. You can indicate support for an existing issuse by voting it up. When submitting a
+bug report, please include a [Gist](http://gist.github.com/) that includes a stack trace and any
+details that may be necessary to reproduce the bug, including your gem version, Ruby version, and
+operating system. Ideally, a bug report should include a pull request with failing specs.
+
+
+Submitting a Pull Request
+-------------------------
+1. Fork the project.
+2. Create a topic branch.
+3. Implement your feature or bug fix.
+4. Add documentation for your feature or bug fix.
+5. Run <tt>rake doc:yard</tt>. If your changes are not 100% documented, go back to step 4.
+6. Add specs for your feature or bug fix.
+7. Run <tt>rake spec</tt>. If your changes are not 100% covered, go back to step 6.
+8. Commit and push your changes.
+9. Submit a pull request. Please do not include changes to the gemspec, version, or history file. (If you want to create your own version for some reason, please do so in a separate commit.)
+
+
+Copyright
+---------
+Copyright (c) 2011 Instagram (Burbn, Inc).
+See [LICENSE](https://github.com/Instagram/instagram-ruby-gem/blob/master/LICENSE.md) for details.

data/Rakefile

@@ -0,0 +1,27 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec
+
+namespace :doc do
+  begin
+    require 'yard'
+  rescue LoadError
+    # ignore
+  else
+    YARD::Rake::YardocTask.new do |task|
+      task.files   = ['HISTORY.mkd', 'LICENSE.mkd', 'lib/**/*.rb']
+      task.options = [
+        '--protected',
+        '--output-dir', 'doc/yard',
+        '--tag', 'format:Supported formats',
+        '--tag', 'authenticated:Requires Authentication',
+        '--tag', 'rate_limited:Rate Limited',
+        '--markup', 'markdown',
+      ]
+    end
+  end
+end

data/lib/faraday/oauth2.rb

@@ -0,0 +1,42 @@
+require 'faraday'
+
+# @private
+module FaradayMiddleware
+  # @private
+  class OAuth2 < Faraday::Middleware
+    def call(env)
+
+      if env[:method] == :get or env[:method] == :delete
+        if env[:url].query.nil?
+          query = {}
+        else
+          query = Faraday::Utils.parse_query(env[:url].query)
+        end
+
+        if @access_token and not query["client_secret"]
+          env[:url].query = Faraday::Utils.build_query(query.merge(:access_token => @access_token))
+          env[:request_headers] = env[:request_headers].merge('Authorization' => "Token token=\"#{@access_token}\"")
+        elsif @client_id
+          env[:url].query = Faraday::Utils.build_query(query.merge(:client_id => @client_id))
+        end
+      else
+        if @access_token and not env[:body] && env[:body][:client_secret]
+          env[:body] = {} if env[:body].nil?
+          env[:body] = env[:body].merge(:access_token => @access_token)
+          env[:request_headers] = env[:request_headers].merge('Authorization' => "Token token=\"#{@access_token}\"")
+        elsif @client_id
+          env[:body] = env[:body].merge(:client_id => @client_id)
+        end
+      end
+
+
+      @app.call env
+    end
+
+    def initialize(app, client_id, access_token=nil)
+      @app = app
+      @client_id = client_id
+      @access_token = access_token
+    end
+  end
+end

data/lib/faraday/raise_http_exception.rb

@@ -0,0 +1,51 @@
+require 'faraday'
+
+# @private
+module FaradayMiddleware
+  # @private
+  class RaiseHttpException < Faraday::Middleware
+    def call(env)
+      @app.call(env).on_complete do |response|
+        case response[:status].to_i
+        when 400
+          raise Instagram::BadRequest, error_message_400(response)
+        when 404
+          raise Instagram::NotFound, error_message_400(response)
+        when 500
+          raise Instagram::InternalServerError, error_message_500(response, "Something is technically wrong.")
+        when 503
+          raise Instagram::ServiceUnavailable, error_message_500(response, "Instagram is rate limiting your requests.")
+        end
+      end
+    end
+
+    def initialize(app)
+      super app
+      @parser = nil
+    end
+
+    private
+
+    def error_message_400(response)
+      "#{response[:method].to_s.upcase} #{response[:url].to_s}: #{response[:status]}#{error_body(response[:body])}"
+    end
+
+    def error_body(body)
+      # body gets passed as a string, not sure if it is passed as something else from other spots?
+      if not body.nil? and not body.empty? and body.kind_of?(String)
+        # removed multi_json thanks to wesnolte's commit
+        body = ::JSON.parse(body)
+      end
+
+      if body.nil?
+        nil
+      elsif body['meta'] and body['meta']['error_message'] and not body['meta']['error_message'].empty?
+        ": #{body['meta']['error_message']}"
+      end
+    end
+
+    def error_message_500(response, body=nil)
+      "#{response[:method].to_s.upcase} #{response[:url].to_s}: #{[response[:status].to_s + ':', body].compact.join(' ')}"
+    end
+  end
+end

data/lib/instagram/api.rb

@@ -0,0 +1,23 @@
+require File.expand_path('../connection', __FILE__)
+require File.expand_path('../request', __FILE__)
+require File.expand_path('../oauth', __FILE__)
+
+module Instagram
+  # @private
+  class API
+    # @private
+    attr_accessor *Configuration::VALID_OPTIONS_KEYS
+
+    # Creates a new API
+    def initialize(options={})
+      options = Instagram.options.merge(options)
+      Configuration::VALID_OPTIONS_KEYS.each do |key|
+        send("#{key}=", options[key])
+      end
+    end
+
+    include Connection
+    include Request
+    include OAuth
+  end
+end

data/lib/instagram/client.rb

@@ -0,0 +1,20 @@
+module Instagram
+  # Wrapper for the Instagram REST API
+  #
+  # @note All methods have been separated into modules and follow the same grouping used in {TODO:doc_URL the Instagram API Documentation}.
+  # @see TODO:doc_url
+  class Client < API
+    Dir[File.expand_path('../client/*.rb', __FILE__)].each{|f| require f}
+
+    include Instagram::Client::Utils
+
+    include Instagram::Client::Users
+    include Instagram::Client::Media
+    include Instagram::Client::Locations
+    include Instagram::Client::Geographies
+    include Instagram::Client::Tags
+    include Instagram::Client::Comments
+    include Instagram::Client::Likes
+    include Instagram::Client::Subscriptions
+  end
+end

data/lib/instagram/client/comments.rb

@@ -0,0 +1,62 @@
+module Instagram
+  class Client
+    # Defines methods related to comments
+    module Comments
+      # Returns a list of comments for a given media item ID
+      #
+      # @overload media_comments(id)
+      #   @param id [Integer] An Instagram media item ID
+      #   @return [Hashie::Mash] The requested comment.
+      #   @example Returns a list of comments for the media item of ID 1234
+      #     Instagram.media_comments(777)
+      # @format :json
+      # @authenticated true
+      #
+      #   If getting this data of a protected user, you must be authenticated (and be allowed to see that user).
+      # @rate_limited true
+      # @see TODO:docs url
+      def media_comments(id, *args)
+        response = get("media/#{id}/comments")
+        response["data"]
+      end
+
+      # Creates a comment for a given media item ID
+      #
+      # @overload create_media_comment(id, text)
+      #   @param id [Integer] An Instagram media item ID
+      #   @param text [String] The text of your comment
+      #   @return [Hashie::Mash] The comment created.
+      #   @example Creates a new comment on media item with ID 777
+      #     Instagram.create_media_comment(777, "Oh noes!")
+      # @format :json
+      # @authenticated true
+      #
+      #   If getting this data of a protected user, you must be authenticated (and be allowed to see that user).
+      # @rate_limited true
+      # @see TODO:docs url
+      def create_media_comment(id, text, options={})
+        response = post("media/#{id}/comments", options.merge(:text => text))
+        response["data"]
+      end
+
+      # Deletes a comment for a given media item ID
+      #
+      # @overload delete_media_comment(media_id, comment_id)
+      #   @param media_id [Integer] An Instagram media item ID.
+      #   @param comment_id [Integer] Your comment ID of the comment you wish to delete.
+      #   @return [nil]
+      #   @example Delete the comment with ID of 1234, on the media item with ID of 777
+      #     Instagram.delete_media_comment(777, 1234)
+      # @format :json
+      # @authenticated true
+      #
+      #   In order to remove a comment, you must be either the owner comment or the media item (or both).
+      # @rate_limited true
+      # @see TODO:docs url
+      def delete_media_comment(media_id, comment_id, options={})
+        response = delete("media/#{media_id}/comments/#{comment_id}", options)
+        response["data"]
+      end
+    end
+  end
+end

data/lib/instagram/client/geographies.rb

@@ -0,0 +1,29 @@
+module Instagram
+  class Client
+    # Defines methods related to real-time geographies
+    module Geographies
+      # Returns a list of recent media items for a given real-time geography
+      #
+      # @overload geography_recent_media(id, options={})
+      #   @param user [Integer] A geography ID from a real-time subscription.
+      #   @param options [Hash] A customizable set of options.
+      #   @option options [Integer] :count (nil) Limit the number of results returned
+      #   @option options [Integer] :min_id (nil) Return media before this min_id
+      #   @option options [Integer] :max_id (nil) Return media after this max_id
+      #   @option options [Integer] :min_timestamp (nil) Return media after this UNIX timestamp
+      #   @option options [Integer] :max_timestamp (nil) Return media before this UNIX timestamp
+      #   @return [Hashie::Mash]
+      #   @example Return a list of the most recent media items taken within a specific geography
+      #     Instagram.geography_recent_media(514276)
+      # @see http://instagram.com/developer/endpoints/geographies/
+      # @format :json
+      # @authenticated false
+      # @rate_limited true
+      def geography_recent_media(id, *args)
+        options = args.last.is_a?(Hash) ? args.pop : {}
+        response = get("geographies/#{id}/media/recent", options)
+        response["data"]
+      end
+    end
+  end
+end

data/lib/instagram/client/likes.rb

@@ -0,0 +1,58 @@
+module Instagram
+  class Client
+    # Defines methods related to likes
+    module Likes
+      # Returns a list of users who like a given media item ID
+      #
+      # @overload media_likes(id)
+      #   @param media [Integer] An Instagram media item ID
+      #   @return [Hashie::Mash] A list of users.
+      #   @example Returns a list of users who like the media item of ID 1234
+      #     Instagram.media_likes(777)
+      # @format :json
+      # @authenticated true
+      #
+      #   If getting this data of a protected user, you must be authenticated (and be allowed to see that user).
+      # @rate_limited true
+      # @see TODO:docs url
+      def media_likes(id, *args)
+        response = get("media/#{id}/likes")
+        response["data"]
+      end
+
+      # Issues a like by the currently authenticated user, for a given media item ID
+      #
+      # @overload like_media(id, text)
+      #   @param id [Integer] An Instagram media item ID
+      #   @return [nil]
+      #   @example Like media item with ID 777
+      #     Instagram.like_media(777)
+      # @format :json
+      # @authenticated true
+      #
+      #   If getting this data of a protected user, you must be authenticated (and be allowed to see that user).
+      # @rate_limited true
+      # @see TODO:docs url
+      def like_media(id, options={})
+        response = post("media/#{id}/likes", options)
+        response["data"]
+      end
+
+      # Removes the like on a givem media item ID for the currently authenticated user
+      #
+      # @overload unlike_media(id)
+      #   @param media_id [Integer] An Instagram media item ID.
+      #   @return [nil]
+      #   @example Remove the like for the currently authenticated user on the media item with the ID of 777
+      #     Instagram.unlike_media(777)
+      # @format :json
+      # @authenticated true
+      # @rate_limited true
+      # @see TODO:docs url
+      def unlike_media(id, options={})
+        response = delete("media/#{id}/likes", options)
+        response["data"]
+      end
+    end
+  end
+end