instagram 0.2.0 → 0.3.0

data/README.md

@@ -1,8 +1,10 @@
-# Instagram Ruby library
+# [Instagram][] Ruby library
 
-So far, the only way to browse [Instagram][] photos was their iPhone app. Well, no more.
+This library acts as a client for the [unofficial Instagram API][wiki]. It was used to create [the missing Instagram web interface][web].
 
-This library acts as a client for the [unofficial Instagram API][wiki]. You can:
+    $ gem install instagram
+
+With it, you can:
 
 * fetch popular photos;
 * get user info;
@@ -19,28 +21,35 @@ Caveat: you need to know user IDs; usernames can't be used. However, you can sta
     
     photo.caption     #=> "Extreme dog closeup"
     photo.likes.size  #=> 54
+    photo.filter_name #=> "X-Pro II"
     
     photo.user.username      #=> "johndoe"
     photo.user.full_name     #=> "John Doe"
     photo.comments[1].text   #=> "That's so cute"
     photo.images.last.width  #=> 612
     
+    # available sizes: 150px / 306px / 612px square
+    photo.image_url(612)
+    # => "http://distillery.s3.amazonaws.com/media/-.jpg" (612×612px image)
     
     # fetch extended info for John
     john_info = Instagram::user_info(photo.user.id)
     
-    john_info.media_count   #=> 32
-    john_info.followers     #=> 160
+    john_info.media_count    #=> 32
+    john_info.follower_count #=> 160
     
     
     # find more photos by John
     photos_by_john = Instagram::by_user(photo.user.id)
 
+To see which models and properties are available, see [models.rb][models].
 
 ## Credits
 
-Instagram API reverse-engineered and Ruby library written by Mislav Marohnić.
+Instagram API documentation and Ruby library written by Mislav Marohnić.
 
 
 [instagram]: http://instagr.am/
-[wiki]: https://github.com/mislav/instagram/wiki "Instagram API"
+[web]: http://instagram.heroku.com
+[wiki]: https://github.com/mislav/instagram/wiki "Instagram API"
+[models]: https://github.com/mislav/instagram/blob/master/lib/instagram/models.rb

data/lib/instagram.rb

@@ -35,7 +35,7 @@ module Instagram
   
   def get_url(url)
     response = Net::HTTP.start(url.host, url.port) { |http|
-      http.get url.request_uri
+      http.get url.request_uri, 'User-agent' => 'Instagram Ruby client'
     }
     
     if Net::HTTPSuccess === response

data/lib/instagram/models.rb

@@ -4,18 +4,22 @@ require 'nibbler/json'
 module Instagram
   
   class Base < NibblerJSON
+    # `pk` is such a dumb property name
     element 'pk' => :id
   end
   
   class User < Base
     element :username
     element :full_name
-    element 'profile_pic_url' => :avatar
+    element 'profile_pic_url' => :avatar_url
+    alias avatar avatar_url # `avatar` is deprecated
     
     # extended info
     element :media_count
-    element 'following_count' => :following
-    element 'follower_count' => :followers
+    element :following_count
+    alias following following_count # `following` will return an array of users in future!
+    element :follower_count
+    alias followers follower_count # `followers` will return an array of users in future!
     
     def ==(other)
       User === other and other.id == self.id
@@ -29,26 +33,39 @@ module Instagram
   end
   
   class Media < Base
+    # short string used for permalink
     element :code
+    # type is always 1 (other values possibly reserved for video in the future?)
     element :media_type
+    # filter code; use `filter_name` to get human name of the filter used
     element :filter_type
+    # I don't know what "device timestamp" is and how it relates to `taken_at`?
     element :device_timestamp
+    # timestamp of when the picture was taken
     element :taken_at, :with => lambda { |sec| Time.at(sec) }
+    # user who uploaded the media
     element :user, :with => User
     
+    # array of people who liked this media
     elements :likers, :with => User
     
     elements :comments, :with => NibblerJSON do
       element :created_at, :with => lambda { |sec| Time.at(sec) }
+      # content type is always "comment"
       element :content_type
+      # `type` is always 1 (other values possibly reserved for comments in form of media?)
       element :type
+      # the `pk` of parent media
       element :media_id
+      # comment body
       element :text
+      # comment author
       element :user, :with => User
     end
     
     elements 'image_versions' => :images, :with => NibblerJSON do
       element :url
+      # `type` is 5 for 150px, 6 for 306px and 7 for 612px
       element :type
       element :width
       element :height
@@ -56,16 +73,59 @@ module Instagram
       alias to_s url
     end
     
+    # image location
+    element :lat
+    element :lng
+    
+    def geolocated?
+      self.lat and self.lng
+    end
+    
+    element :location, :with => Base do
+      # ID on a 3rd-party service
+      element :external_id
+      # name of 3rd-party service, like "foursquare"
+      element :external_source
+      # name of location
+      element :name
+      # address in the external service's database
+      element :address
+      element :lat
+      element :lng
+    end
+    
+    # author's caption for the image; can be nil
     def caption
-      # a bit of guesswork
+      # caption is implemented as a first comment made by the owner
       if comments.first and self.user == comments.first.user
         comments.first.text
       end
     end
     
+    # typical sizes: 150px / 306px / 612px square
     def image_url(size = 150)
       self.images.find { |img| img.width == size }.to_s
     end
+    
+    FILTERS = {
+      1  => 'X-Pro II',
+      2  => 'Lomo-fi',
+      3  => 'Earlybird',
+      17 => 'Lily',
+      5  => 'Poprocket',
+      18 => 'Sutro',
+      19 => 'Toaster',
+      10 => 'Inkwell',
+      4  => 'Apollo',
+      15 => 'Nashville',
+      13 => 'Gotham',
+      14 => '1977',
+      16 => 'Lord Kelvin'
+    }
+    
+    def filter_name
+      FILTERS[filter_type.to_i]
+    end
   end
   
   class Timeline < NibblerJSON

metadata

@@ -4,9 +4,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 0
-  - 2
+  - 3
   - 0
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors: 
 - "Mislav Marohni\xC4\x87"
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-12-07 00:00:00 +01:00
+date: 2010-12-27 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency