Permalink
Browse files

Merge pull request #26 from pamelafox/patch-2

Adding more information to the README.
  • Loading branch information...
mikeyk committed May 27, 2012
2 parents 7b7e3f4 + 53e1a7f commit 212ea9216b08cd5eadb78f21177c2e7e7e02ed2d
Showing with 131 additions and 8 deletions.
  1. +131 −8 README.md
View
139 README.md
@@ -18,26 +18,149 @@ Discussion
Visit [our Google Group](http://groups.google.com/group/instagram-api-developers) to discuss the Instagram API.
-Obtaining an access token
+Authentication
-----
-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.
-Usage
------
+Instagram API uses the OAuth2 protocol for authentication, but not all functionality requires authentication.
+See the docs for more information: http://instagr.am/developer/auth/
+
+### Obtaining an access token
+
+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.
+
+### Authenticating a user
+
+The provided sample app shows a simple OAuth flow for authenticating a user and getting an access token for them.
+
+### Using an access token
+
+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 = "..."
+ access_token = "YOUR_ACCESS_TOKEN"
api = InstagramAPI(access_token=access_token)
+ recent_media, next = instagram_client.user_recent_media(user_id=user.instagram_userid, count=count)
+ for media in recent_media:
+ print media.caption.text
+
+### Making unauthenticated requests
+
+For 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'].url
+
+Real-time Subscriptions:
+-----
+
+See 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)
+
+
+Data Retrieval:
+-----
+
+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)
+
+
+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)
+
+
+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_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)
+
+Geographies: http://instagr.am/developer/endpoints/geographies/
+
+ api.geography_recent_media(count, max_id, geography_id)*
+
+
Sample app
------
-We also provide a one-file sample app using bottle (you'll have to 'pip install bottle' first). To try it out:
+This repository includes a one-file sample app that uses the bottle framework and demonstrates
+authentication, subscriptions, and update processing. To try it out:
+ * Download bottle if you don't already have it: pip install bottle
* Set your redirect URI to 'http://localhost:8515/oauth_callback' in your dev profile
* Open up sample\_app.py, update it with your client\_id and secret, and set redirect URI to 'http://localhost:8515/oauth_callback'
* Run the file; it will host a local server on port 8515.

0 comments on commit 212ea92

Please sign in to comment.