From The Blog

Import Gmail Contacts using Ruby on Rails

In the past importing Gmail contacts was a bit of a hassle. One of the previous options was to use the Contacts gem found at RubyForge. However, now...

In the past importing Gmail contacts was a bit of a hassle. One of the previous options was to use the Contacts gem found at RubyForge. However, now that the Google Contacts API has been released, it offers a more secure (and hopefully reliable) way to retrieve contacts. The Contacts API allows redirecting and authenticating users through Google, instead of forcing them enter their Gmail password into a third party application. Here is a quick tutorial to get up and running in ruby on rails with the Gmail Contacts API.

First, you need to register your domain with Google. This can be as easy as uploading a temporary file to your domain’s root directory to verify control of the domain. The steps for doing this are clearly outlined at Registration for Web-Based Applications.

Once you’ve verified control of the domain with google, start making your requests! Grabbing the contacts is essentially a three step process:

  • Initiate the authentication with Gmail. Send your user over to enter their credentials, after which Google passes back an AuthSub token valid for one request.
  • Send back the one-time AuthSub token and exchange it for a long-lived token valid for multiple requests.
  • Use this second token to make requests to the Gmail Contacts API and import user’s Gmail contacts.

    More detailed steps on how Google Authentication process works can be found at Authentication for Web Applications

Now lets visit the three steps above in more detail, and implement importing gmail contacts using ruby on rails!

1. First redirect your users to authenticate with Gmail and request a one-time use AuthSub token.

# initiate authentication w/ gmail
  #
  # create url with url-encoded params to initiate connection with contacts api
  #
  # next - The URL of the page that Google should redirect the user to after authentication.
  # scope - Indicates that the application is requesting a token to access contacts feeds. 
  # secure - Indicates whether the client is requesting a secure token.
  # session - Indicates whether the token returned can be exchanged for a multi-use (session) token.
  #  
  next_param = "http%3A%2F%2Fwww.example.com%2F"
  scope_param = "http%3A%2F%2Fwww.google.com%2Fm8%2Ffeeds%2F"
  secure_param = "0"
  session_param = "1"
  root_url = "https://www.google.com/accounts/AuthSubRequest"
  query_string = "?scope=#{scope_param}&session=#{session_param}&secure=#{secure_param}&next=#{next_param}"
  redirect_to root_url + query_string

2. Trade your single-use token for the all powerful AuthSub session token.

  require 'net/http'
  require 'net/https'
 
  token = params[:token] # received the single-use authsub token, exchange for authsub session token
 
  http = Net::HTTP.new('www.google.com', 443)
  http.use_ssl = true
  path = '/accounts/AuthSubSessionToken'
  headers = {'Authorization' => "AuthSubtoken="#{token}""}
  resp, data = http.get(path, headers)
 
  if resp.code == "200" 
    token = ''
    data.split.each do |str|
      if not (str =~ /Token=/).nil?
        token = str.gsub(/Token=/, '')   
      end
    end
    redirect_to "http://www.example.com/?token=#{token}"
  else  
    redirect_to "http://www.example.com/"
  end

Note: There’s probably a better way to grab the above token from the response, if anyone would like to suggest a refactoring here please feel free . . .

3. Finally, grab your buddies!

# GET http://www.google.com/m8/feeds/contacts/default/base
require 'net/http'
require 'rexml/document'      
 
http = Net::HTTP.new('www.google.com', 80)
# by default Google returns 50? contacts at a time.  Set max-results to very high number
# in order to retrieve more contacts
path = "/m8/feeds/contacts/default/base?max-results=10000"
headers = {'Authorization' => "AuthSubtoken="#{authsub_token}""}
resp, data = http.get(path, headers)
 
# extract the name and email address from the response data
xml = REXML::Document.new(data)
contacts = []
xml.elements.each('//entry') do |entry|
  person = {}
  person['name'] = entry.elements['title'].text
 
  gd_email = entry.elements['gd:email']
  person['email'] = gd_email.attributes['address'] if gd_email
 
  contacts << person
end

Hopefully that should help get you started on the right track. The Google Contacts API allows retrieval of other information besides simply name and email address. I’d be interested in hearing what else is everyone using/doing with this API?

Other Posts That Might Interest You

  1. Proving the Productivity of Ruby on Rails with the Rails Rumble
  2. TDD On The Bleeding Edge With Ruby 1.9.3, Rails 3, RSpec, Cucumber, Autotest, and Factory Girl
  3. Easy PDF Generation with Ruby, Rails, and HTMLDOC

Tags: 

  • I've wrapped the code up in a few classes and created a demo app for people that wanted to get a head start. No tests or much error exception as of yet but I'll hopefully worked towards that.

    http://github.com/maran/Gmail-Contacts-Demo/tre...
  • UP
    I mean “AuthSubtoken="#{authsub_token}"” --> not working

    “AuthSubtoken=#{authsub_token}” --> working
  • UP
    One fix that I needed this to work - you need to remove the outer quotes from around the token parameter.
    Btw, the article by IrishPenguin was superb...helped me understand where to hang off all the code!

    "AuthSubtoken=#{authsub_token}"
  • Very nice how-to, congrats
  • leomayleomay
    Hi,
    why I can't set secure_param to be 1, every time I set this variable to be 1, I get the 403 code. Can anyone help to explain why?

    Thank you.

    BTW, I've uploaded a .pem file in "Manager Your Domain".

    Great article.
  • Thanks! This is very useful. Following your post, I wrote up a blog entry providing code for securely requesting the token here: http://blog.guitarati.com/2008/08/google-accoun...
  • Not yet, but that's a great idea! I'll let Tom know.
  • Hey, just wondering if you have pluginized this yet?

    Great writeup!

    Jason
  • Hi, thanks for the great article. I've just added a few clarifications for newbies on my own site at
    http://www.theirishpenguin.com/2008/06/25/a-lit...

    Thanks again!
    The Irish Penguin
  • Thanks for the info, it really helped.
  • Or, simply use the Google Contacts Data API implemented in Ruby: http://github.com/mislav/contacts/tree/master
  • danbram
    Pardon the ignorance Mislav, but how do I register during development? Is there an alternative to make this work while using http:localhost:3000???
  • For the java developers that visit this website i point to
    http://code.google.com/p/contactlistimporter/
    for an implementation in java.

    The contactlistimporter that i created supports different services for importing contacts.
  • vanderkerkoff
    good work fella
  • Nice tutorial!
  • Thanks, it's my first encounter with Google's new APIs and this is very helpful.

    A minor note to others, in the last step you'd need to set:

    authsub_token = params[:token]
  • Thanks for this simple howto.
blog comments powered by Disqus