Ruby library for consuming Google, Yahoo!, Flickr and Windows Live contact APIs
Switch branches/tags
Pull request Compare This branch is 1 commit ahead of animoto:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


Basic usage instructions

Fetch users' contact lists from your web application without asking them to provide their passwords.

First, register your application's domain. Then make users follow this URL:


They will authenticate on Google and it will send them back to the URL provided. Google will add a token GET parameter to the query part of the URL. Use that token in the next step:

gmail =[:token])
# => [#<Contact 1>, #<Contact 2>, ...]

The resulting Contacts::Contact objects have `name` and `email` properties.

Read more in Contacts::Google. I plan to support more APIs (Microsoft Live, for starters); feel free to contribute.

Author: Mislav Marohnić (

Documentation specific to SunDawg fork

This project was forked from the original project by Mislav in order to support GData signed requests. Specific to this fork are the following:

  • detecting Windows Live cancel authorization

  • JSON changes for Yahoo.

  • supported for signed requests using GData protocol

  • fixed Fakeweb deprecation issues and fixed for version 1.2.7

Signed requests are required to remove security warnings on Google authorization requests. In order to use secure settings, do the following when generating an authorizational_url:

Contacts::Google.authentication_url(YOUR_CALLBACK_URL, :session => true, :secure => true)

When you try to promote the authentication token returned to your callback into a session token, you must set the private key before promotion.

You can set the private key as so:


If this is successful, you will have a session token that can be used to fetch contact information.

The key can be a file path or in memory string of the key you generated.

The certificate that is generated with your key must be registered with Google:

For more information on secure session requirements for Google and signatures:

Documentation auto-generated from specifications


  • generates a URL for target with default parameters

  • should handle boolean parameters

  • skips parameters that have nil value

  • should be able to exchange one-time for session token


  • fetches contacts feed via HTTP GET

  • handles a normal response body

  • handles gzipped response

  • raises a FetchingError when something goes awry

  • parses the resulting feed into name/email pairs

  • parses a complex feed into name/email pairs

  • makes modification time available after parsing

Contacts::Google GET query parameter handling

  • abstracts ugly parameters behind nicer ones

  • should have implicit :descending with :order

  • should have default :limit of 200

  • should skip nil values in parameters