Cocoafish Ruby API
Switch branches/tags
Nothing to show
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

Cocoafish Ruby Client

This is a Ruby client for the Cocoafish server backand that can be used in your Ruby scripts and Ruby on Rails apps. For full documentation about the API methods that can be used through this gem, see the Cocoafish REST API documentation. This has been developed and tested with Ruby 1.8.7/1.9.2 and Rails 3.0.5. Earlier versions of Ruby or Rails may not work.


Cocoafish is currently in Private Beta. Before your app can access the Cocoafish API servers, you must:

  1. Request a Beta invitation code at
  2. Use the Beta invitation code to create an account at
  3. Register your app at to generate an app key, OAuth consumer key, and OAuth secret



For Rails 3, add the Cocoafish gem to your Gemfile:

gem 'cocoafish'

and install with bundler:

# bundle install


For plain Ruby manually install the Cocoafish gem:

# sudo gem install cocoafish

Then include it in your scripts:

require 'rubygems'
require 'cocoafish'


Authenticating with Cocoafish

Find the OAuth consumer key and secret for your app on the Cocoafish app management site and use them to set the credentials so that your app can talk to the Cocoafish API servers.

Cocoafish::Client.set_credentials('key', 'secret')

By default the Ruby Client uses http. If you wish to use https (SSL) to send requests to Cocoafish, you can use the hostname option:

Cocoafish::Client.set_credentials('key', 'secret', {:hostname=>""})

Making Requests

Use the Cocoafish client http methods to store and retrive data with Cocoafish by passing a url path and optional parameters hash:

result =, params = {})
result = Cocoafish::Client.get(path, params = {})
result = Cocoafish::Client.put(path, params = {})
result = Cocoafish::Client.delete(path, params = {})

The url path is the suffix of a Cocoafish REST API call such as:

result = Cocoafish::Client.get("places/show.json", {:place_id => "4e10f444d0afbe4156000019"})
result ="users/login.json", {:login => "", :password => "cocoafish"})

Processing Responses

Cocoafish API servers return data in JSON format:

  "meta": {
    "status": "ok",
    "code": 200,
    "method_name": "createUser",
    "session_id": "6z4xBTs-cg1fL7U7RGVDSw_9vC8"
  "response": {
    "users": [
        "id": "4ec4c607356f4e12c8000035",
        "first_name": "Jane",
        "last_name": "User",
        "created_at": "2011-11-17T08:29:59+0000",
        "updated_at": "2011-11-17T08:29:59+0000",
        "email": ""

The Ruby client library provides the response wrapped in an object accessible through dot notation:

result ="users/login.json", {:login => "", :password => "cocoafish"})
puts result.response.users[0].id
 => 4ec4c870356f4e12c8000038
puts result.response.users[0].first_name
 => Jane

Or, the original JSON reponse string can be accessed:

result ="users/login.json", {:login => "", :password => "cocoafish"})
json_result = JSON.parse(result.json)
puts result.response.users[0].id
 => 4ec4c870356f4e12c8000038
puts json_result["response"]["users"][0]['first_name']
 => Jane

The response code and message can be retreived through the meta:

puts result.meta.status
 => ok
puts result.meta.code
 => 200
puts result.meta.method_name
 => createUser

Handling Errors

Errors returned from the Cocoafish API will be thrown as an exception. Wrap Cocoaifsh client calls in a begin/rescue block to capture and handle them gracefully.

  result ="users/login.json", {:login => "", :password => "cocoafish"})
rescue Cocoafish::CocoafishError => e
  puts "Login failed: #{e.message}"

Code Samples

Checkin App Example

The following script shows how to perform actions required for a checkin app: create users, create places, checkin to places with photos, and search for checkins by location.

require 'rubygems'
require 'cocoafish'

# set Oauth consumer key and secret from your app
Cocoafish::Client.set_credentials("7z5w8Jcg3iUemGab9ugty15oacju8fSF", "Jxc18og2eq1G0Mg9jAFoE3CUfCUdFS6L")

#  create a user which logs her in automatically
result ="users/create.json", {:email => "", :password => "cocoafish", :password_confirmation => "cocoafish", :first_name => "Jane", :last_name => "User"})

# create a place
result ="places/create.json", {:name => "Cocoafish HQ", :address => "156 2nd St", :city => "San Francisco", :state => "CA", :postal_code => "94107", :latitude => 37.787099, :longitude => -122.399101})
place_1_id = result.response.places[0].id

# checkin to the place with a photo and message
photo ="/Users/mgoff/Desktop/atwork.jpg", "rb")
result ="checkins/create.json", {:message => "Working hard!", :photo => photo, "photo_sync_sizes[]" => "large_1024", :place_id => place_1_id})

# create another place
result ="places/create.json", {:name => "Kingdom of Dumpling", :address => "1713 Taraval St", :city => "San Francisco", :state => "CA", :postal_code => "94116", :latitude => 37.742640, :longitude => -122.484597})
place_2_id = result.response.places[0].id

# checkin to the place with a photo and message
photo ="/Users/mgoff/Desktop/dumplings.jpg", "rb")
result ="checkins/create.json", {:message => "Eating some awesome Chinese dumplings!", :photo => photo, "photo_sync_sizes[]" => "large_1024", :place_id => place_2_id})

# search for checkins from my current location in Union Square
result = Cocoafish::Client.get("checkins/search.json", {:latitude => 37.787930, :longitude => -122.407499})

# loop through the results and print them out
result.response.checkins.each_with_index do |checkin, index|
  puts "Checkin #{index}"
  puts "  User:    #{checkin.user.first_name} #{checkin.user.last_name}"
  puts "  Place:   #{}"
  puts "  Message: #{checkin.message}"
  puts "  Photo:   #{}\n\n"

Running this script performs the actions and shows the nearby checkins along with URLs for the uploaded checkin photos:

Checkin 0
  User:    Jane User
  Place:   Cocoafish HQ
  Message: Working hard!

Checkin 1
  User:    Jane User
  Place:   Kingdom of Dumpling
  Message: Eating some awesome Chinese dumplings!

Additional APIs

For more examples of API usage see the Cocoafish REST API documentation.


Copyright (c) 2011 Cocoafish. See LICENSE.txt for further details.


For questions or comments about the Cocoafish Ruby client gem, or about Cocoafish in general, contact