ADS specializes in using Ruby on Rails to build advanced, scalable, database-backed web sites for organizations of all sizes. Find out more at our website.

Apr: 18; 2008

Import Gmail Contacts using Ruby on Rails

By: Tom Hunter | Tags:

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?

Share this post

21 Responses to “Import Gmail Contacts using Ruby on Rails”

On April 18th, 2008 at 1:53 pm Import Gmail Contacts using Ruby on Rails | Contacts City said:

[...] Read the rest of this great post here [...]

On April 19th, 2008 at 2:19 am Barry said:

Thanks for this simple howto.

On April 19th, 2008 at 5:09 pm Marko said:

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]

On April 20th, 2008 at 11:32 pm links for 2008-04-21 at Topper’s Blog said:

[...] Import Gmail Contacts using Ruby on Rails | Atlantic Dominion Solutions (tags: google api howto tutorials) [...]

On April 21st, 2008 at 12:02 am Import Gmail Contacts using Ruby on Rails | Atlantic Dominion Solutions said:

[...] Go! the coyote says Share and Enjoy: These icons link to social bookmarking sites where readers can share and discover new web pages. [...]

On April 21st, 2008 at 3:15 am roScripts - Webmaster resources and websites said:

Import Gmail Contacts using Ruby on Rails | Atlantic Dominion Solutions…

Need help with your ruby programming project Atlantic Dominion Solutions s developers can ensure you maximize your web programming technology with Ruby…

On April 21st, 2008 at 3:20 am This Week in Ruby (April 21, 2008) | Zen and the Art of Programming said:

[...] week two must-read, hands-on posts were published: Import Gmail Contacts using Ruby on Rails and Paperclip: Attaching Files in Rails. Both cover tasks that are extremely common and useful for [...]

On April 21st, 2008 at 3:45 am Mithun said:

Nice tutorial!

On April 21st, 2008 at 9:35 am links for 2008-04-21 « Brent Sordyl’s Blog said:

[...] Google Contacts API using Ruby on Rails The Google Contacts API has been released, it offers a more secure (and hopefully reliable) way to retrieve contacts. Tutorial on doing so using Ruby on Rails (tags: gmail google api rubyonrails) [...]

On April 21st, 2008 at 10:24 am Web 2.0 Announcer said:

Import Gmail Contacts using Ruby on Rails…

[...]Tutorial on importing Gmail contacts with Ruby on Rails and the new Google Contacts API[...]…

On April 21st, 2008 at 11:33 am links for 2008-04-21, or so says Harry Love said:

[...] Import Gmail Contacts using Ruby on Rails | Atlantic Dominion Solutions (tags: ruby rubyonrails gmail google) [...]

On April 22nd, 2008 at 1:36 am links for 2008-04-22 | Libin Pan said:

[...] Import Gmail Contacts using Ruby on Rails | Atlantic Dominion Solutions Here is a quick tutorial to get up and running in ruby on rails with the Gmail Contacts API. (tags: authentication gmail rails google ruby contacts api rubyonrails programming development) [...]

On April 22nd, 2008 at 10:19 am vanderkerkoff said:

good work fella

On April 23rd, 2008 at 3:55 am Tjerk Wolterink said:

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.

On April 23rd, 2008 at 4:25 am Web 2.0 Announcer said:

Import Gmail Contacts using Ruby on Rails | Atlantic Dominion Solutions…

[...][...]…

On April 23rd, 2008 at 3:30 pm Mislav said:

Or, simply use the Google Contacts Data API implemented in Ruby: http://github.com/mislav/contacts/tree/master

On April 25th, 2008 at 4:20 pm Links interessantes — Learning on Rails said:

[...] Import GMail contacts using Rails [...]

On May 27th, 2008 at 9:32 am Just imported my first Google Contacts l … « Paul M. Watson said:

[...] pm on May 27, 2008 | # | Tags: dev Just imported my first Google Contacts list, nice tutorial here. [...]

On May 27th, 2008 at 9:32 am Paul M. Watson said:

Thanks for the info, it really helped.

On June 24th, 2008 at 3:46 pm The Irish Penguin » Blog Archive » A Little Help on Importing Gmail Contacts using Ruby on Rails said:

[...] came across a fabulous article on getting your RoR app to pull contacts from your Gmail account at Atlantic Domain Solutions: Import Gmail Contacts using Ruby on Rails. Kudos to Atlantic Domain Solutions! This is a really great article. The only slight issue is that [...]

On June 24th, 2008 at 3:55 pm The Irish Penguin said:

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-little-help-on-importing-gmail-contacts-using-ruby-on-rails

Thanks again!
The Irish Penguin