Ruby Script to Download Google Account Contacts

Chad Albers

August 8, 2008

1. Overview

downloadGoogleContacts.rb is a fairly robust Ruby script that uses Google's Contacts Data API to download your Contacts from either a Gmail account or a "hosted" Google account. I wrote the script to download and backup all my Contacts on a regular basis using cron. The script uses Google's ClientLogin interface to access the account. It then downloads the contacts as an Atom XML feed.

The script "works for me” and should be considered an early beta version.

2. Script Options and Parameters

The script requires three mandatory options:

  • -e or --email EMAIL_ADDRESS

    The e-mail address of the Google account, including both the username and either Google's domain (@gmail.com), or the hosted account's domain (@neomantic.com).

  • -p or --password PASSWORD

    The password of the Google account or hosted Google account.

  • -t or --tokenfile FULL_PATH_TO_FILE

    The file name and path to the file where the script has or will save the ClientLogin token.

  • -o or --output FULL_PATH_TO_FILE

    The file name and path to the file where the script has or will save the Atom Feed of the Contacts.

The script accepts one optional option that modifies the output:

  • -m --maximum MAXIMUM_NUMBER_OF_CONTACTS

    The maximum number of contacts to retrieve. (Without supplying this parameter, the number of Contacts returned is relatively small.)

The script also accepts two more optional options:

  • -v or --verbose

    Provides messages on the script's progress.

  • -h or --help

    Provides a message describing these options.

3. Usage Example

To download all your Contacts to a file called “contacts.xml” using a key stored in a file called “token_file,” run the following command:

$> ruby downloadGoogleContacts.rb -e myGoogleAccount@address.com -p sekritpassword -m 10000 -t /home/my_home/token_file -o /home/my_home/contacts.xml

4. Script Requirements

The script does not depend on any third-party Ruby code outside of Ruby's Core and Standard Libraries. It has been tested successfully on Ruby 1.8.7 (on Debian GNU/Linux).

5. Limitations

  • OpenSSL: The script makes no attempt to verify the certificate used to encrypt the transmission between sending login information and Google's website. Ruby's https class can perform this verification, but the script intentionally disables it - using OpenSSL::SSL::VERIFY_NONE. To perform the verification, the script would need to include the certificate from Googles' CA. This feature can be enabled by following the instructions posted on this web page.

  • CAPTCHA: The script can handle a number of user, system, and network errors. It can also handle errors noticed by Google. However, it cannot handle the case when Google notifies the user that they must re-verify their login information by viewing a CAPTCHA image.

6. License

The source code is released under the GNU General Public License Version 2 (GPL). The full text of this license can be found in a file called “gpl-2.0” released with the source code.

This documentation is released under the GNU Free Documentation License Version 1.2.

Copyright (c) Chad Albers. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".

The full text of this license is found in the file called “fdl.txt” released with the source code.

7. Download Location

The source code and documentation can be downloaded from here. The GPG signature of this file can be found here. Updates to the script will be posted to http://www.neomantic.com

8. Contact

Please direct questions or requests for more information to . Corrections, suggestions, bug reports, and patches are welcome as well.