Instagram Basic Display

This is a client gem for Instagram’s Basic Display API. It’s a small wrapper around the API that provides access to users’ media and profile information. Not every endpoint has been implemented, so pull requests are welcome to round things out!

Updates to the documentation are also very welcome!

Installation

Add this line to your application's Gemfile:

gem 'instagram_basic_display'

And then execute:

$ bundle

Or install it yourself as:

$ gem install instagram_basic_display

Usage and examples

Configuration

Set three environment variables to configure the client:

INSTAGRAM_CLIENT_ID=your_client_id
INSTAGRAM_CLIENT_SECRET=your_client_secret
INSTAGRAM_REDIRECT_URI=your_redirect_url

These variables can be obtained from the Facebook developer console.

Using the client

When initializing the client, you can optionally pass in an auth token from Instagram, which will be used to make further requests. If you do not already have a token, you can use one of the methods provided to retrieve one.

client = InstagramBasicDisplay::Client.new

# OR

client = InstagramBasicDisplay::Client.new(auth_token: token)

Getting auth tokens

Authenticating with Instagram starts with an access code. This access code is retrieved by implementing Instagram's authortization window, and is not covered by this gem.

Once you have an access code, you can exchange it for a short-lived authentication token.

user = User.first
client = InstagramBasicDisplay::Client.new

short_token_request = client.short_lived_token(access_code: code)

if short_token_request.success?
  auth_token = token_request.payload.access_token
  expires_in = token_request.payload.expires_in
  user.update_instagram_token(token: token, expires_in: expires_in)
else
  render json: short_token_request.error, status: 400
end

You can exchange your short-lived token for a long-lived token.

client = InstagramBasicDisplay::Client.new
user = User.first

long_token_request = client.long_lived_token(short_lived_token: user.instagram_token)

if long_token_request.success?
  auth_token = token_request.payload.access_token
  expires_in = token_request.payload.expires_in
  user.update_instagram_token(token: token, expires_in: expires_in)
else
  render json: long_token_request.error, status: 400
end

You can also pass an access code to #long_lived_token. It will be exchanged for a short-lived token, and then that will immediately be exchanged for a long-lived token.

access_code = params[:access_code]
client = InstagramBasicDisplay::Client.new
user = User.first

long_token_request = client.long_lived_token(access_code: access_code)

if long_token_request.success?
  auth_token = token_request.payload.access_token
  expires_in = token_request.payload.expires_in
  user.update_instagram_token(token: token, expires_in: expires_in)
else
  render json: long_token_request.error, status: 400
end

You can refresh a long-lived token so that it remains valid for another period (at this stage, Instagram have set the validity period to 60 days).

user = User.first
client = InstagramBasicDisplay::Client.new

refresh_request = client.refresh_long_lived_token(token: user.instagram_token)

if refresh_request.success?
  client.update_instagram_token(token: token_request.payload.access_token)
else
  render json: refresh_request.error, status: 400
end

To use an auth token when making requests, you can either pass it in when initializing the client, or on-the-fly.

auth_token = User.first.instagram_token

client = InstagramBasicDisplay::Client.new(auth_token: auth_token)

# OR

client = InstagramBasicDisplay::Client.new
client.configuration.auth_token = auth_token

Getting profile information

You can retrieve a user's profile information (e.g. their username and Instagram id).

If no user_id is provided, the request will be made against the user associated with the client's auth token. For example:

auth_token = User.first.instagram_token

client = InstagramBasicDisplay::Client.new(auth_token: auth_token)
response = client.profile

instagram_id = response.payload.id
instagram_username = response.payload.username

But you can also pass in a user_id, and request specific profile fields. Check the Instagram documentation to find out which fields are supported.

user = User.first

client = InstagramBasicDisplay::Client.new(auth_token: user.instagram_token)
response = client.profile(user_id: user.instagram_id, fields: %i[username])

instagram_username = response.payload.username

Getting media

You can query a user's media feed like this:

user = User.first

client = InstagramBasicDisplay::Client.new(auth_token: user.instagram_token)
response = client.media_feed

media = response.payload.data

You can query for specific fields on the media, but by default you'll receive the id and media_url of each item. Refer to the Instagram documentation to find out about other fields.

user = User.first

client = InstagramBasicDisplay::Client.new(auth_token: user.instagram_token)
response = client.media_feed(fields: %i[caption media_url])

media = response.payload.data

For pagination, the Instagram API provides previous/next links. Use those to retrieve the next page of results.

user = User.first

client = InstagramBasicDisplay::Client.new(auth_token: user.instagram_token)

first_page = client.media_feed(fields: %i[caption media_url])

# you can ask the response whether there is a next/previous page
has_next_page_link = first_page.next_page?

# or ask for the url
next_page_link = first_page.next_page_link

second_page = client.media_feed(fields: %i[caption media_url], paginated_url: next_page_link)

You can pass some additional parameters to the media feed. They aren't yet well-documented by Instagram, but you can make some reasonable guesses at what will be accepted, based on the Facebook API. For example, to limit the number of results retrieved:

user = User.first

client = InstagramBasicDisplay::Client.new(auth_token: user.instagram_token)
client.media_feed(limit: 10)

To retrieve a single piece of media, you'll need to know its id. As with the other requests, you can request whichever fields are supported by Instagram.

user = User.first
client = InstagramBasicDisplay::Client.new(auth_token: user.instagram_token)

client.media_node(media_id: id, fields: %i[caption media_url id])

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/convertkit/instagram_basic_display. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.