Instagram API

This gem is a simple and easy to use wrapper for Instagram's API.

Documentation

The documentation for this gem can be found at rdoc.info/gems/instagram_api.

Installation

Add this line to your application's Gemfile:

gem 'instagram_api'

And then execute:

$ bundle

Or install it yourself as:

$ gem install instagram_api

Usage

require 'instagram_api'

All methods in Instagram's API require some kind of authentication. You can retrieve any public data by using just your client ID, but it is recommended to authorize yourself (and your users) using an access_token. You can get your client ID and client secret by visiting http://instagram.com/developer.

# Instantiate a new client.
client = Instagram.client(
  :client_id     => '2bfe9d72a4aae8f06a31025b7536be80',
  :client_secret => '9d667c2b7fae7a329f32b6df17926154',
  :callback_url  => 'http://example.com/'
)

# Visit the authorization URL in your browser and login.
client.authorize_url
# => "https://api.instagram.com/oauth/authorize/?client_id=2bfe9d72a4aae8f06a31025b7536be80&redirect_uri=http://example.com/&response_type=code"

# Retrieve the code from the URL parameters and use it to get an access token.
client.get_access_token('88fb89ab65454da2a06f2c6dacd09436')
# => '1313345.3fedf64.a0fcb7f40e02fe3da50500'

The last method, get_access_token, will return your access token as well as set it for your client. You can then access any method in the API using your client.

Alternatively, after you or your user have authenticated, you can reinstantiate your client using the previously returned access token.

client = Instagram.client(:access_token => '1313345.3fedf64.a0fcb7f40e02fe3da50500')

Users API Methods

You can access various information about Instagram users by using the following methods:

# Get a user information by id or username.
client.user(16500486)
client.user('caseyscarborough')

# Get the authenticated user's information.
client.user

# Search for a user by username.
client.search('github')

# Retrieve an authenticated user's feed.
client.feed

# Get a user's recent updates.
client.recent(16500486)

# Retrieve an authenticated user's updates.
client.recent

# Get an authenticated user's liked photos/videos.
client.liked

See the Instagram User Endpoints for more information.

Media API Methods

You can retrieve media information by using the following methods:

# Get information about a media object by its ID.
client.media(42020)

# Search for a media item by latitude and longitude (required),
# with distance constraints (default 1000 meters).
client.media_search(:lat => "48.858844", :lng => "2.294351")
client.media_search(:lat => "48.858844", :lng => "2.294351", :distance => 2000)

# Search with Unix timestamp constraints.
client.media_search(
  :lat => "48.858844",
  :lng => "2.294351",
  :min_timestamp => 1357020000,
  :max_timestamp => 1375246800
)

# Get a list of popular media at the moment.
client.popular_media

See the Instagram Media Endpoints for more information.

Sample Application

The following is a sample application using this gem and Sinatra. Make sure that the sinatra and instagram_api gems are installed before running it.

$ gem install sinatra instagram_api

Afterwards, copy the contents of the following file into a file called sample.rb and add your client ID and client secret (retrieved by registering a new application at http://instagram.com/developer).

require 'sinatra'
require 'instagram_api'

# Go to http://instagram.com/developer to get your client ID and client secret.
CLIENT_ID = "YOUR CLIENT ID"
CLIENT_SECRET = "YOUR CLIENT SECRET"

# Set the redirect uri for your application to the following:
REDIRECT_URI = "http://localhost:4567/callback"

client = Instagram.client(
  :client_id => CLIENT_ID,
  :client_secret => CLIENT_SECRET,
  :callback_url => REDIRECT_URI
)

get '/' do
  output = '<h2>Popular Media</h2>'
  client.popular_media.data.each do |p|
    output << "<a href='#{p.link}'><img src='#{p.images.thumbnail.url}'></a>&nbsp;"
  end
  output << '<br /><h3><a href="/auth">Click here</a> to authenticate with Instagram.</h3>'
  output
end

get '/auth' do
  redirect client.authorize_url
end

get '/callback' do
  client.get_access_token(params[:code])
  redirect '/dashboard'
end

get '/dashboard' do
  user = client.user
  output = "<h2>#{user.data.username}'s feed</h2>"
  client.feed.data.each do |f|
    output << "<a href='#{f.link}'><img src='#{f.images.low_resolution.url}'></a><br />
    <img src='#{f.user.profile_picture}' width='20'>&nbsp;#{f.user.username}<br /><br />"
  end
  output
end

You can then run the application by issuing the following command from the file's directory:

$ ruby sample.rb

Then navigate to localhost:4567 to see the application in action.

You can view/download this file here.

Supported Ruby Versions

These are the currently supported Ruby versions:

Ruby 1.8.7
Ruby 1.9.2
Ruby 1.9.3
Ruby 2.0.0

This library may work on other versions of Ruby, but these are the versions that the library is tested against.

Contributing

Fork it
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create new Pull Request

instagram_api

Development

Runtime