This project is not actively maintained. Proceed at your own risk!
A Python 2/3 client for the Instagram REST and Search APIs
pip install instagram
- httplib2
- simplejson
- six
- pytz
The Instagram developer page supposedly documents all the Instagram REST and Search APIs.
The Instagram for developers blog features news and important announcements about the Instagram Platform.
You will also find tutorials and best practices to help you build great platform integrations.
The Stack Overflow instagram tag is a great place to ask API related questions or if you need help with your code.
Make sure to tag your questions with the Instagram tag to get fast answers from other fellow developers and members of the Instagram team.
Instagram API uses the OAuth2 protocol for authentication, but not all functionality requires authentication. See the docs for more information: http://instagram.com/developer/authentication/
If you're using a method that requires authentication and need an access token, you can use the provided get_access_token.py script to obtain an access token for yourself. It will prompt you for your app's Client ID, Client Secret, and Redirect URI, and walk you through instructions for getting your own access token for your app.
The provided sample app shows a simple OAuth flow for authenticating a user and getting an access token for them.
Once you have an access token (whether via the script or from the user flow), you can pass that token into the InstagramAPI constructor:
from instagram.client import InstagramAPI
access_token = "YOUR_ACCESS_TOKEN"
client_secret = "YOUR_CLIENT_SECRET"
api = InstagramAPI(access_token=access_token, client_secret=client_secret)
recent_media, next_ = api.user_recent_media(user_id="userid", count=10)
for media in recent_media:
print media.caption.textFor methods that don't require authentication, you can just pass your client ID and optionally client secret into the InstagramAPI constructor:
api = InstagramAPI(client_id='YOUR_CLIENT_ID', client_secret='YOUR_CLIENT_SECRET')
popular_media = api.media_popular(count=20)
for media in popular_media:
print media.images['standard_resolution'].urlSee the docs for more on real-time subscriptions: http://instagr.am/developer/realtime/
You can use the API to subscribe to users, tags, locations, or geographies:
# Subscribe to updates for all users authenticated to your app
api.create_subscription(object='user', aspect='media', callback_url='http://mydomain.com/hook/instagram')
# Subscribe to all media tagged with 'fox'
api.create_subscription(object='tag', object_id='fox', aspect='media', callback_url='http://mydomain.com/hook/instagram')
# Subscribe to all media in a given location
api.create_subscription(object='location', object_id='1257285', aspect='media', callback_url='http://mydomain.com/hook/instagram')
# Subscribe to all media in a geographic area
api.create_subscription(object='geography', lat=35.657872, lng=139.70232, radius=1000, aspect='media', callback_url='http://mydomain.com/hook/instagram')Along with that, you would typically register subscription "reactors" for processing the different subscription types:
# React to user type updates
reactor = subscriptions.SubscriptionsReactor()
reactor.register_callback(subscriptions.SubscriptionType.USER, process_user_update)See the provided sample app for an example of making a subscription, reacting to it, an processing the updates.
You can also use the API to list and delete subscriptions:
api.list_subscriptions()
api.delete_subscriptions(id=342342)See the endpoints docs for more on these methods: http://instagr.am/developer/endpoints/
The methods with a * return two values, where the second is a pagination parameter. Here's an example of retrieving recent media:
recent_media, next_ = api.user_recent_media()
photos = []
for media in recent_media:
photos.append('<img src="%s"/>' % media.images['thumbnail'].url)And an example of exhaustively pursuing a paginated endpoint:
follows, next_ = api.user_follows()
while next_:
more_follows, next_ = api.user_follows(with_next_url=next_)
follows.extend(more_follows)Users: http://instagr.am/developer/endpoints/users/
api.user(user_id)
api.user_media_feed()*
api.user_liked_media()*
api.user_recent_media(user_id, count, max_id)*
api.user_search(q, count, lat, lng, min_timestamp, max_timestamp)Relationships: http://instagr.am/developer/endpoints/relationships/
api.user_incoming_requests()
api.user_follows(user_id)*
api.user_followed_by(user_id)*
api.follow_user(user_id)
api.unfollow_user(user_id)
api.block_user(user_id)
api.unblock_user(user_id)
api.approve_user_request(user_id)
api.ignore_user_request(user_id)
api.user_relationship(user_id)Media: http://instagr.am/developer/endpoints/media/
api.media(media_id)
api.media_popular(count, max_id)
api.media_search(q, count, lat, lng, min_timestamp, max_timestamp)Comments: http://instagr.am/developer/endpoints/comments/
api.media_comments(media_id)
api.create_media_comment(media_id, text)
api.delete_comment(media_id, comment_id)Likes: http://instagr.am/developer/endpoints/likes/
api.media_likes(media_id)
api.like_media(media_id)
api.unlike_media(media_id)Tags: http://instagr.am/developer/endpoints/tags/
api.tag(tag_name)
api.tag_recent_media(count, max_tag_id, tag_name)*
api.tag_search(q, count)*Locations: http://instagr.am/developer/endpoints/locations/
api.location(location_id)
api.location_recent_media(count, max_id, location_id)*
api.location_search(q, count, lat, lng, foursquare_id, foursquare_v2_id)Geographies: http://instagr.am/developer/endpoints/geographies/
api.geography_recent_media(count, max_id, geography_id)*Importing the bind module allows handling of specific error status codes. An example is provided below:
from instagram.bind import InstagramAPIError
try:
# your code goes here
except InstagramAPIError as e:
if (e.status_code == 400):
print "\nUser is set to private."By default there is no timeout for requests to the Instagram API. You can specify a timeout in one of two ways:
from instagram.client import InstagramAPI
# set a 30-second timeout for this particular InstagramAPI instance
api = InstagramAPI(access_token=access_token, client_secret=client_secret, timeout=30)or
import socket
# Set the global default timeout, which applies to all sockets in your
# program where a timeout is not otherwise specified.
socket.setdefaulttimeout(30)If you get an error of a module not being defined during the Instagram import call, this might update a necessary package.
sudo pip install --upgrade six
In the spirit of free software, 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
- by reviewing patches
We use the GitHub issue tracker 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 issue by voting it up. When submitting a bug report, please include a Gist that includes a stack trace and any details that may be necessary to reproduce the bug, including your version number, and operating system. Ideally, a bug report should include a pull request with failing specs.
Instagram has a bounty program for the safe disclosure of security bugs. In those cases, please go through the process outlined on that page and do not file a public issue.
- Fork the project.
- Create a topic branch.
- Implement your feature or bug fix.
- Run python tests.py .
- Add a test for your feature or bug fix.
- Run python tests.py . If your changes are not 100% covered, go back to step 5.
- Commit and push your changes.
- Submit a pull request.
- If you haven't already, complete the Contributor License Agreement ("CLA").
In order to accept your pull request, we need you to submit a CLA. You only need to do this once to work on any of Instagram's or Facebook's open source projects.
Complete your CLA here: https://code.facebook.com/cla
Copyright (c) 2014, Facebook, Inc. All rights reserved. By contributing to python-instagram, you agree that your contributions will be licensed under its BSD license. See LICENSE for details.