Skip to content
This repository
Browse code

Merge pull request #26 from pamelafox/patch-2

Adding more information to the README.
  • Loading branch information...
commit 212ea9216b08cd5eadb78f21177c2e7e7e02ed2d 2 parents 7b7e3f4 + 53e1a7f
Mike Krieger authored May 26, 2012

Showing 1 changed file with 131 additions and 8 deletions. Show diff stats Hide diff stats

  1. 139  README.md
139  README.md
Source Rendered
@@ -18,26 +18,149 @@ Discussion
18 18
 Visit [our Google Group](http://groups.google.com/group/instagram-api-developers) to discuss the Instagram API.
19 19
 
20 20
 
21  
-Obtaining an access token
  21
+Authentication
22 22
 -----
23  
-You can use the provided get_access_token.py script to obtain an access token for yourself.
24  
-It will prompt you for your app's Client ID, Client Secret, and Redirect URI,
25  
-and walk you through instructions for getting your own access token for your app.
26 23
 
27  
-Usage
28  
------
  24
+Instagram API uses the OAuth2 protocol for authentication, but not all functionality requires authentication.
  25
+See the docs for more information: http://instagr.am/developer/auth/
  26
+
  27
+### Obtaining an access token
  28
+
  29
+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.
  30
+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.
  31
+
  32
+### Authenticating a user
  33
+
  34
+The provided sample app shows a simple OAuth flow for authenticating a user and getting an access token for them.
  35
+
  36
+### Using an access token
  37
+
  38
+Once you have an access token (whether via the script or from the user flow), you can  pass that token into the InstagramAPI constructor:
  39
+
29 40
     from instagram.client import InstagramAPI
30 41
 
31  
-    access_token = "..."
  42
+    access_token = "YOUR_ACCESS_TOKEN"
32 43
     api = InstagramAPI(access_token=access_token)
  44
+    recent_media, next = instagram_client.user_recent_media(user_id=user.instagram_userid, count=count)
  45
+    for media in recent_media:
  46
+       print media.caption.text
  47
+       
  48
+### Making unauthenticated requests
  49
+
  50
+For methods that don't require authentication, you can just pass your client ID and optionally client secret into the InstagramAPI 
  51
+constructor:
  52
+
  53
+    api = InstagramAPI(client_id='YOUR_CLIENT_ID', client_secret='YOUR_CLIENT_SECRET')
33 54
     popular_media = api.media_popular(count=20)
34 55
     for media in popular_media:
35 56
         print media.images['standard_resolution'].url
36 57
 
  58
+
  59
+Real-time Subscriptions:
  60
+-----
  61
+
  62
+See the docs for more on real-time subscriptions: http://instagr.am/developer/realtime/
  63
+
  64
+You can use the API to subscribe to users, tags, locations, or geographies:
  65
+
  66
+    # Subscribe to updates for all users authenticated to your app
  67
+    api.create_subscription(object='user', aspect='media', callback_url='http://mydomain.com/hook/instagram')
  68
+    # Subscribe to all media tagged with 'fox'
  69
+    api.create_subscription(object='tag', object_id='fox', aspect='media', callback_url='http://mydomain.com/hook/instagram')
  70
+    # Subscribe to all media in a given location
  71
+    api.create_subscription(object='location', object_id='1257285', aspect='media', callback_url='http://mydomain.com/hook/instagram')
  72
+    # Subscribe to all media in a geographic area
  73
+    api.create_subscription(object='geography', lat=35.657872, lng=139.70232, radius=1000, aspect='media', callback_url='http://mydomain.com/hook/instagram')
  74
+ 
  75
+Along with that, you would typically register subscription "reactors" for processing the different subscription types:
  76
+
  77
+    # React to user type updates
  78
+    reactor = subscriptions.SubscriptionsReactor()
  79
+    reactor.register_callback(subscriptions.SubscriptionType.USER, process_user_update)
  80
+    
  81
+See the provided sample app for an example of making a subscription, reacting to it, an processing the updates.
  82
+
  83
+You can also use the API to list and delete subscriptions:
  84
+    api.list_subscriptions()
  85
+    api.delete_subscriptions(id=342342)
  86
+   
  87
+
  88
+Data Retrieval:
  89
+-----
  90
+
  91
+See the endpoints docs for more on these methods: http://instagr.am/developer/endpoints/
  92
+
  93
+The methods with a * return two values, where the second is a pagination parameter. Here's an example of retrieving recent media:
  94
+
  95
+    recent_media, next = api.user_recent_media()
  96
+    photos = []
  97
+    for media in recent_media:
  98
+        photos.append('<img src="%s"/>' % media.images['thumbnail'].url)
  99
+            
  100
+
  101
+Users: http://instagr.am/developer/endpoints/users/
  102
+    
  103
+    api.user(user_id)
  104
+    api.user_media_feed()*
  105
+    api.user_liked_media()*
  106
+    api.user_recent_media(user_id, count, max_id)*
  107
+    api.user_search(q, count, lat, lng, min_timestamp, max_timestamp)
  108
+    
  109
+   
  110
+Relationships: http://instagr.am/developer/endpoints/relationships/
  111
+
  112
+    api.user_incoming_requests()
  113
+    api.user_follows(user_id)*
  114
+    api.user_followed_by(user_id)*
  115
+    api.follow_user(user_id)
  116
+    api.unfollow_user(user_id)
  117
+    api.block_user(user_id)
  118
+    api.unblock_user(user_id)
  119
+    api.approve_user_request(user_id)
  120
+    api.ignore_user_request(user_id)
  121
+
  122
+
  123
+Media: http://instagr.am/developer/endpoints/media/
  124
+
  125
+    api.media(media_id)
  126
+    api.media_popular(count, max_id)
  127
+    api.media_search(q, count, lat, lng, min_timestamp, max_timestamp)
  128
+    
  129
+Comments: http://instagr.am/developer/endpoints/comments/
  130
+
  131
+    api.media_comments(media_id)
  132
+    api.create_media_comment(media_id, text)
  133
+    api.delete_comment(media_id, comment_id)
  134
+    
  135
+Likes: http://instagr.am/developer/endpoints/likes/
  136
+
  137
+    api.media_likes(media_id)
  138
+    api.like_media(media_id)
  139
+    api.unlike_media(media_id)
  140
+    
  141
+Tags: http://instagr.am/developer/endpoints/tags/
  142
+
  143
+    api.tag(tag_name) 
  144
+    api.tag_recent_media(count, max_id, tag_name)*
  145
+    api.tag_search(q, count)*
  146
+ 
  147
+Locations: http://instagr.am/developer/endpoints/locations/
  148
+
  149
+    api.location(location_id)
  150
+    api.location_recent_media(count, max_id, location_id)*
  151
+    api.location_search(q, count, lat, lng, foursquare_id)
  152
+    
  153
+Geographies: http://instagr.am/developer/endpoints/geographies/
  154
+
  155
+    api.geography_recent_media(count, max_id, geography_id)*
  156
+
  157
+
37 158
 Sample app
38 159
 ------
39  
-We also provide a one-file sample app using bottle (you'll have to 'pip install bottle' first). To try it out:
  160
+This repository includes a one-file sample app that uses the bottle framework and demonstrates
  161
+authentication, subscriptions, and update processing. To try it out:
40 162
 
  163
+  * Download bottle if you don't already have it: pip install bottle
41 164
   * Set your redirect URI to 'http://localhost:8515/oauth_callback' in your dev profile
42 165
   * Open up sample\_app.py, update it with your client\_id and secret, and set redirect URI to 'http://localhost:8515/oauth_callback'
43 166
   * Run the file; it will host a local server on port 8515.

0 notes on commit 212ea92

Please sign in to comment.
Something went wrong with that request. Please try again.