aliang / google_contacts_api

Google Contacts API for ruby, unofficial

google_contacts_api

An unofficial Google Contacts API for ruby. Might not be stable (but probably is).

Do the tests pass?

Upgrading

Right now upgrading should just work, barring any bugs in my implementation. In the next major version I will probably drop (or at least stop maintaining) support for OAuth::AccessToken objects and depend directly on the oauth2 gem.

Usage

You need to pass to the GoogleContactsApi::User constructor one of the following two objects:

• an OAuth::AccessToken from the oauth-ruby gem
• an OAuth2::AccessToken from the oauth2 gem

See their respective documentation for details on how to get this object. (I'm guessing there would be a few changes in implementation details of the GoogleContactsApi::Api class if you use another OAuth library, mostly to change how the base get/post/put/delete methods work.)

Then you can instantiate a GoogleContactsApi::Api object for direct posting and parsing, or a GoogleContactsApi::User object for easier stuff.

oauth_access_token_for_user
# => <OAuth2::AccessToken:0x000000029a69d36>

google_contacts_user = GoogleContactsApi::User.new(oauth_access_token_for_user)
contacts = google_contacts_user.contacts
# => <GoogleContactsApi::ContactSet: @start_index=1, @items_per_page=100000, @total_results=638>
groups = google_contacts_user.groups
# => <GoogleContactsApi::GroupSet: @start_index=1, @items_per_page=100000, @total_results=8>

# group methods
group = groups.first
# => <GoogleContactsApi::Group: System Group: My Contacts>
group.contacts
# => <GoogleContactsApi::ContactSet: @start_index=1, @items_per_page=100000, @total_results=20>

# creating or deleting a group
new_group = google_contacts_user.create_group('New group')
api.delete_group(new_group)

# contact methods
contact = contacts.first
# => <GoogleContactsApi::Contact: Alvin>
contact.photo
contact.title
contact.id
contact.primary_email
contact.emails

ContactSet and GroupSet both implement Enumberable.

In addition, Contact and Group are subclasses of Hashie::Mash, so you can access any of the underlying data directly (for example, if Google returns new data in their API). Note that data is retrieved using Google's JSON API so the equivalent content of an XML element from the XML API is stored under the key "$t".

The easiest way to see the convenience methods I've provided is to look at the RSpec tests.

TODO

I welcome patches and pull requests, see the guidelines below (handily auto-generated by jeweler).

• Any missing tests! (using RSpec, please)
• Read more contact information (structured name, address, ...)
• Get single contacts and groups
• Posting/putting/deleting contacts and their photos. This might require XML?
• Adapter layer for different OAuth libraries? I'm not sure there are any other widely used libraries though
• Support ClientLogin (maybe not, since Google's old library covers it)

Contributing to google_contacts_api

• Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
• Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
• Fork the project
• Start a feature/bugfix branch
• Commit and push until you are happy with your contribution
• Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
• Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.

Copyright

Copyright (c) 2011-15 Alvin Liang (aliang). See LICENSE.txt for further details.

• Some code based on a few bugfixes in lfittl and fraudpointer forks.
• Support for Google Contacts API version 3 fields by draffensperger.
• Additional specs and empty GroupSet entry fix by Jeiwan.

google_contacts_api's Issues

Getting contacts from Access Token

Hi,

I am using GoogleOauth2 strategy in my application and upon authentication, the strategy is giving me OauthHash with access_token and refresh_token. I am not sure how to proceed with using that data to get contacts. the contacts API is asking for OAuth2::AccessToken object but i am getting Omniauth::AuthHash from strategy. Any idea how to get the same?

uninitialized constant Api::TransactionController::GoogleContactsApi

I am getting following error

uninitialized constant Api::TransactionController::GoogleContactsApi

when i try to initiliaze the constructor

google_contacts_user = GoogleContactsApi::User.new(oauth_access_token_for_user)

Support for Service Accounts?

I am trying to use this gem to authenticate my web application with the contacts API to create new contacts for a specific user. My assumption is that the underlying google account user who enables the contacts API on the console.developers.google.com portal can create service accounts that access its contact data. If this assumption is right, then using this gem should allow me to use application default credentials https://developers.google.com/identity/protocols/application-default-credentials to fetch that data using a service account instead of a Client-Server authentication workflow, which it seems that this gem primarily supports.

Any ideas on how I can use this gem to perform a server-to-server authentication workflow using application default credentials instead of a client-server one? Thanks in advance!

Set up testing with live account

You could pass the Google Account you want to use and possibly password as environment variables, and it could run a test on Google's servers.

This is to protect against API changes on Google's end

Also include an OAuth2 example in README

A lot of people have trouble getting the access token from Google's server

implement inspect method for User

We don't really need to see the gory details of the Api object, do we?

implement ResultSet.next_page method

Return nil or empty result set if no next page. Raise error or return nil if no api object is given

Got an answer for this one?

http://stackoverflow.com/questions/31151310/what-is-the-id-of-the-starred-contacts-group-in-the-google-contacts-api

I can't seem to get the contacts in the starred group. Will your library do that?

Thanks @aliang

Sort/Order functionality?

hi, I'm loving your gem. Right now, calling contacts returns all of a user's contacts. Ideally, I'd like to get back "Most Contacted or Frequently Contacted" but after researching it appears that is not available via the APIs. The 2nd best idea is to return the contacts sorted by:

query.orderby = 'lastmodified'

Which apparently is the default setting listed here: https://developers.google.com/google-apps/contacts/v3/#retrieving_contacts_using_query_parameters

However, this gem doesn't seem to have any sort order, the ordering appears to be random.

With your gem is it possible to sort or return just the X last modified contacts? Or better yet, per the contact record include a "last_modified" timestamp?

Thank you again for all the work! It's really great and helpful

Turn oauth2 access_token string into object? (OmniAuth & OAuth2)

After a user oauth's with omniauth we save the oauth_token as a string. In this gem you require the access_token as an object. How do we go from one to the other?

oAuth instructions

Awesome gem, thanks a lot for your hard work.

I struggle to connect through oAuth, would you mind giving detailed step by step instructions on what to do to obtain the oauth_access_token_for_user?

Deprecate OAuth 1.0

It's all OAuth 2.0 now

Add contact to google contacts

can we add a new contacts by using this gem?