Cameraplus (Camera+)

This gem provides a Ruby wrapper around the Camera+ API, using HTTParty. Camera+ is an iPhone photo app made by tap tap tap with effects made by professional photographer Lisa Bettany. Cameraplus is based on the Web Sharing API.

Installation

Add this line to your application's Gemfile:

gem 'cameraplus'

And then execute:

$ bundle

Or install it yourself as:

$ gem install cameraplus

Cameraplus::API

Cameraplus::API is a very thin wrapper for the Camera+ API. It uses the bare minimum to get the diserable data from Camera+ and returns it as a Hash.

Cameraplus::API::User

Cameraplus::API::User.find("mostlylisa") # => Retrieves a hash with user data of Twitter user @mostlylisa (Twitter account of Lisa Bettany)

Cameraplus::API::Page

Cameraplus::API::Page.find("b72Z") # => Retrieves a hash with the metadata of the specified page

Cameraplus layer

The Cameraplus gem also provides a 'convenience' layer. This layer lies on top of Cameraplus::API, which only returns hashes. The Cameraplus layer has an easier interface which returns objects like Cameraplus::User, Cameraplus::Page and Cameraplus::Photo.

Retrieving a user with `Cameraplus::User`

A user can be retrieved with the following line of code:

@user = Cameraplus::User.find("mostlylisa")

The @user variable provides access to the following properties:

@user.id            # => 6978642
@user.username      # => mostlylisa (this is a Twitter username)
@user.name          # => Lisa Bettany
@user.avatar        # => http://a0.twimg.com/profile_images/1767370289/284161_10150711631895637_674215636_19658534_6246798_n_normal.jpeg
@user.page_count    # => 122
@user.photo_count   # => 876

Retrieving pages from a user

A list with pages is also included in the response of the above call:

@user.pages         # => [ #<Cameraplus::Page:0x007fb5c2f91080>, #<Cameraplus::Page:0x007fb5c2f9e5f0>, ... ]

Yeah, it's that easy. The above returns an Array with Cameraplus::Page objects. Provided that you've only selected the first page with @page = @user.pages.first. The @page variable will now have the following properties:

@page.url           # => http://campl.us/iao4
@page.created_at    # => 2012-03-14 22:53:49
@page.location      # => 45.43383498680353 12.34226474539595
@page.location_name # => Venice, Venice
@page.tweet_text    # => Carnival in Venice, a travel photographer's dream shoot!
@page.tweet_id      # => 180064216093437954 (the actual id on Twitter)
@page.view_count    # => 2101
@page.comment_count # => 1

Assuming that you'll want to create a list of the pages of the specified user, the following can be done in Haml:

%ul
  - @user.pages.each do |page|
    %li
      = "#{page.tweet_text} at #{page.location_name} on #{page.created_at.strftime("%d %b %Y")}"

This will generate a list of pages with a maximum of 50 (in case each page has a single photo). The number of pages depends on the number of photos a page has. In case a page has 50 photos, it will only return a single page.

Retrieving the photos from the pages

Just like the Cameraplus::User instance has access to it's pages, a Cameraplus::Page in turn has access to it's photos:

@page.photos        # => [ #<Cameraplus::Photo:0x007fb5c2f90a90>, #<Cameraplus::Photo:0x007fb5c2f9b300>, ... ]

The above returns an Array with Cameraplus::Photo objects. Again, assuming that you've selected the first photo on the page with: @photo = @page.photos.first, it will have access to the below properties:

@photo.small        # => http://pics.campl.us/t/0/0b497f01791c851db1a17f81e0621a5c.jpg
@photo.medium       # => http://pics.campl.us/iphone/0/0b497f01791c851db1a17f81e0621a5c.jpg
@photo.large        # => http://pics.campl.us/f/0/0b497f01791c851db1a17f81e0621a5c.jpg
@photo.width        # => 800
@photo.height       # => 590
@photo.location     # => 45.43383498680353 12.34226474539595

In case you want to list all the large versions of the photos retrieved by the above call, you could do the following and loop through them afterwards:

@large_photos = @user.pages.map { |page| page.map(&:large) }.flatten

Retrieving the next set of pages

When a user has more pages than the results of @user.pages, the next set of pages can be retrieved with @user.more_pages. This doesn't only return the new set of pages though. It also retrieves the user data. The result is exactly the same as @user only with a new list of pages and calling .more_pages on the new object returns even more of them (if they exist).

PageMetadata

The Camera+ Web Sharing API doesn't return all the details of a page through the earlier mentioned API call, which is made by the Cameraplus::API::User class. The Cameraplus::API::Page class however does retrieve all of the desired data. The Cameraplus::PageMetadata class basically is a layer on top of that API class.

Retrieving metadata from the page is as easy as:

@metadata = Cameraplus::PageMetadata.find("b72Z")

The argument "b72Z" is the identifier of the page and is being used in the actual URL. The first page retrieved in 'Retrieving pages from a user' has the following url: 'http://campl.us/iao4', iao4 in this url would be used as a parameter in the above call. The following properties can be accessed on a Cameraplus::PageMetadata instance:

@metadata.url           # => http://campl.us/b72Z
@metadata.created_at    # => 2011-07-01 21:50:40
@metadata.location      # => nil
@metadata.location_name # => nil
@metadata.tweet_text    # => Tiny Town of Kotor, Montenegro #mybestphoto
@metadata.tweet_id      # => 86914646237384704 (the actual id on Twitter)
@metadata.view_count    # => 925
@metadata.comment_count # => 6

As you can see, these properties are identical to the properties of a Cameraplus::Page, but it also adds a lot more.

Retrieving the user belonging to the page

The user who owns the page can be accessed with:

@user = @metadata.user

You might expect the same properties as you'll get from the previous user call, this isn't the case though. The response of this requested call doesn't include #page_count and #photo_count. This leaves you with the properties:

@user.id            # => 14199276
@user.username      # => lucyk
@user.name          # => Oleg Lutsenko
@user.avatar        # => http://a0.twimg.com/profile_images/1318866321/avatar1_sqr_normal.jpg

Retrieving the photos belonging to the page

All of the photos which are included on the specified page are presented to you by calling:

@photos = @metadata.photos

These photos have the same properties as mentioned previously with the addition of exif data and recipes. The basic Cameraplus::Photo object has these properties:

@photo.small        # => http://pics.campl.us/t/f/f2cc65ab786741e7ab9fb994d06626a6.jpg
@photo.medium       # => http://pics.campl.us/iphone/f/f2cc65ab786741e7ab9fb994d06626a6.jpg
@photo.large        # => http://pics.campl.us/f/f/f2cc65ab786741e7ab9fb994d06626a6.jpg
@photo.width        # => 800
@photo.height       # => 597
@photo.location     # => nil

The added functionality is described below.

Retrieving the exif data from a photo

As mentioned in the previous part, a Cameraplus::Photo object has more than just the default properties. It also includes exif data of the actual photo. The data can be accessed as follows:

@exif_data = @photo.exif

The above will return an Array with Cameraplus::PhotoExif objects, selecting the first item of the Array (@exif = @exif_data.first) will return the following:

@exif.title         # => Camera
@exif.value         # => Apple iPhone
@exif.style         # => main

Exif data can include options like: Camera (Apple iPhone 4s), Software (Camera+ 2.2.1), Exposure (1/580 sec), Aperture (f/2.4) and Focal length (3.9 mm).

Retrieving the recipe from a photo

An instance of Cameraplus::Photo also has an Array called recipes with any of the effects, in the form of a Cameraplus::PhotoRecipe object, which were applied to it in the Camera+ iPhone app. A recipe has two properties:

@recipe.type        # => fx
@recipe.value       # => Miniaturize (80%)

The recipes of a photo can be accessed through: @photo.recipes.

Retrieving the comments belonging to the page

People can comment on the photo or photos you've taken. Those comments are made available through the API. Accessing them is done by calling:

@comments = @metadata.comments

The Array contains Cameraplus::Comment instances with these properties:

@comment.author     # => Lisa Bettany
@comment.avatar     # => https://fbcdn-profile-a.akamaihd.net/hprofile-ak-snc4/261022_674215636_4030749_q.jpg
@comment.url        # => http://www.facebook.com/profile.php?id=674215636
@comment.text       # => great shot!

Once again, the above comment was retrieved by accessing the first element of the Array.

Search

It's also possible to search for a user, pages or photos. There is a single call for this, which is:

@results = Cameraplus::Search.find username: "mostlylisa"

This will retrieve an Array with Cameraplus::Search objects. Each of these has three properties:

@result.page        # => #<Cameraplus::Page:0x007fb5c2f91080>
@result.user        # => #<Cameraplus::User:0x007fcfd54aec08>
@result.photos      # => [ #<Cameraplus::Photo:0x007fb5c2f90a90>, #<Cameraplus::Photo:0x007fb5c2f9b300>, ... ]

Again, this is assuming that we've selected the first result with: @result = @results.first.

Possible arguments for a search

As seen in the previous call, a hash is required for a search. It needs at least one argument. The possible properties of the hash are: username, tweettext, earliest, latest and locationname. Below is list of these properties with it's types and descriptions:

username      String            Twitter username
tweettext     String            Tweet text partial search
earliest      YYYY-MM-DD HH:MM  Return only tweets on or after this date/time (UTC)
latest        YYYY-MM-DD HH:MM  Return only tweets on or before this date/time (UTC)
locationname  String            Location name string partial match. Note: location names are missing for pages created before March, 2011.

Contributing

You're very welcome to contribute to this gem. To do so, please follow these steps:

Fork this project
Clone your fork on your local machine
Install the development dependencies with bundle install
Create your feature branch with git checkout -b my-new-feature
Run the specs with rspec and make sure everything is covered with RSpec
Commit your changes git commit -am 'Added new feature'
Push to your branch git push origin my-new-feature
Create a new Pull Request