{"id":25328659,"url":"https://github.com/kit/instagram_basic_display","last_synced_at":"2025-10-29T04:32:30.267Z","repository":{"id":56877730,"uuid":"235091598","full_name":"Kit/instagram_basic_display","owner":"Kit","description":"A client gem for the Instagram Basic Display API","archived":false,"fork":false,"pushed_at":"2024-11-26T15:12:43.000Z","size":64,"stargazers_count":25,"open_issues_count":2,"forks_count":10,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-02-12T14:59:37.667Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Kit.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-01-20T12:00:27.000Z","updated_at":"2024-11-26T14:29:21.000Z","dependencies_parsed_at":"2024-12-26T18:18:51.187Z","dependency_job_id":"ae9cb83b-3c94-4671-a89a-9120fcfaa42a","html_url":"https://github.com/Kit/instagram_basic_display","commit_stats":null,"previous_names":["kit/instagram_basic_display","convertkit/instagram_basic_display"],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kit%2Finstagram_basic_display","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kit%2Finstagram_basic_display/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kit%2Finstagram_basic_display/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kit%2Finstagram_basic_display/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Kit","download_url":"https://codeload.github.com/Kit/instagram_basic_display/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238772126,"owners_count":19527879,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-02-14T02:56:32.100Z","updated_at":"2025-10-29T04:32:29.945Z","avatar_url":"https://github.com/Kit.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Instagram Basic Display\n\nThis is a client gem for Instagram’s [Basic Display API](https://developers.facebook.com/docs/instagram-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!\n\nUpdates to the documentation are also very welcome!\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'instagram_basic_display'\n```\n\nAnd then execute:\n\n    $ bundle\n\nOr install it yourself as:\n\n    $ gem install instagram_basic_display\n\n## Usage and examples\n\n### Configuration\n\nSet three environment variables to configure the client:\n\n```\nINSTAGRAM_CLIENT_ID=your_client_id\nINSTAGRAM_CLIENT_SECRET=your_client_secret\nINSTAGRAM_REDIRECT_URI=your_redirect_url\n```\n\nThese variables can be obtained from the Facebook developer console.\n\n### Using the client\n\nWhen 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.\n\n```ruby\nclient = InstagramBasicDisplay::Client.new\n\n# OR\n\nclient = InstagramBasicDisplay::Client.new(auth_token: token)\n```\n\n### Getting auth tokens\n\nAuthenticating with Instagram starts with an access code. This access code is retrieved by implementing Instagram's [authortization window](https://developers.facebook.com/docs/instagram-basic-display-api/overview#authorization-window), and is not covered by this gem.\n\nOnce you have an access code, you can exchange it for a short-lived authentication token.\n\n```ruby\nuser = User.first\nclient = InstagramBasicDisplay::Client.new\n\nshort_token_request = client.short_lived_token(access_code: code)\n\nif short_token_request.success?\n  auth_token = token_request.payload.access_token\n  expires_in = token_request.payload.expires_in\n  user.update_instagram_token(token: token, expires_in: expires_in)\nelse\n  render json: short_token_request.error, status: 400\nend\n```\n\nYou can exchange your short-lived token for a long-lived token.\n\n```ruby\nclient = InstagramBasicDisplay::Client.new\nuser = User.first\n\nlong_token_request = client.long_lived_token(short_lived_token: user.instagram_token)\n\nif long_token_request.success?\n  auth_token = token_request.payload.access_token\n  expires_in = token_request.payload.expires_in\n  user.update_instagram_token(token: token, expires_in: expires_in)\nelse\n  render json: long_token_request.error, status: 400\nend\n```\n\nYou 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.\n\n```ruby\naccess_code = params[:access_code]\nclient = InstagramBasicDisplay::Client.new\nuser = User.first\n\nlong_token_request = client.long_lived_token(access_code: access_code)\n\nif long_token_request.success?\n  auth_token = token_request.payload.access_token\n  expires_in = token_request.payload.expires_in\n  user.update_instagram_token(token: token, expires_in: expires_in)\nelse\n  render json: long_token_request.error, status: 400\nend\n```\n\nYou 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).\n\n```ruby\nuser = User.first\nclient = InstagramBasicDisplay::Client.new\n\nrefresh_request = client.refresh_long_lived_token(token: user.instagram_token)\n\nif refresh_request.success?\n  client.update_instagram_token(token: token_request.payload.access_token)\nelse\n  render json: refresh_request.error, status: 400\nend\n```\n\nTo use an auth token when making requests, you can either pass it in when initializing the client,\nor on-the-fly.\n\n```ruby\nauth_token = User.first.instagram_token\n\nclient = InstagramBasicDisplay::Client.new(auth_token: auth_token)\n\n# OR\n\nclient = InstagramBasicDisplay::Client.new\nclient.configuration.auth_token = auth_token\n```\n\n### Getting profile information\n\nYou can retrieve a user's profile information (e.g. their username and Instagram id).\n\nIf no `user_id` is provided, the request will be made against the user associated with the client's auth token. For example:\n\n```ruby\nauth_token = User.first.instagram_token\n\nclient = InstagramBasicDisplay::Client.new(auth_token: auth_token)\nresponse = client.profile\n\ninstagram_id = response.payload.id\ninstagram_username = response.payload.username\n```\n\nBut you can also pass in a `user_id`, and request specific profile fields. Check the Instagram documentation to find out [which fields are supported](https://developers.facebook.com/docs/instagram-basic-display-api/reference/user#fields).\n\n```ruby\nuser = User.first\n\nclient = InstagramBasicDisplay::Client.new(auth_token: user.instagram_token)\nresponse = client.profile(user_id: user.instagram_id, fields: %i[username])\n\ninstagram_username = response.payload.username\n```\n\n### Getting media\n\nYou can query a user's media feed like this:\n\n```ruby\nuser = User.first\n\nclient = InstagramBasicDisplay::Client.new(auth_token: user.instagram_token)\nresponse = client.media_feed\n\nmedia = response.payload.data\n```\n\nYou 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](https://developers.facebook.com/docs/instagram-basic-display-api/reference/media/).\n\n```ruby\nuser = User.first\n\nclient = InstagramBasicDisplay::Client.new(auth_token: user.instagram_token)\nresponse = client.media_feed(fields: %i[caption media_url])\n\nmedia = response.payload.data\n```\n\nFor pagination, the Instagram API provides previous/next links. Use those to retrieve the next page of results.\n\n```ruby\n\nuser = User.first\n\nclient = InstagramBasicDisplay::Client.new(auth_token: user.instagram_token)\n\nfirst_page = client.media_feed(fields: %i[caption media_url])\n\n# you can ask the response whether there is a next/previous page\nhas_next_page_link = first_page.next_page?\n\n# or ask for the url\nnext_page_link = first_page.next_page_link\n\nsecond_page = client.media_feed(fields: %i[caption media_url], paginated_url: next_page_link)\n```\n\nYou 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:\n\n```ruby\nuser = User.first\n\nclient = InstagramBasicDisplay::Client.new(auth_token: user.instagram_token)\nclient.media_feed(limit: 10)\n```\n\nTo 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.\n\n```ruby\nuser = User.first\nclient = InstagramBasicDisplay::Client.new(auth_token: user.instagram_token)\n\nclient.media_node(media_id: id, fields: %i[caption media_url id])\n```\n\n## Development\n\nAfter 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.\n\nTo 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](https://rubygems.org).\n\n## Contributing\n\nBug 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](http://contributor-covenant.org) code of conduct.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkit%2Finstagram_basic_display","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkit%2Finstagram_basic_display","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkit%2Finstagram_basic_display/lists"}