To enhance the user experience for inviting your friends to take a look Magnet.me, we decided to include a feature to import contacts from your Google account. There are multiple ways to approach this, including a client-side only approach with the use of just javascript. This should be an easy process to set up, however in practice this was not the case as we ran into some problems. This blogpost will describe the problems we experienced and provide solutions to these problems.

Problems

Google API explorer

Google has APIs for multiple purposes. For example, I could use a Google API to create short urls (like http://goo.gl/Mp8EjW)) or communicate with Google Plus. Google has set up an API explorer webpage where every developer can find information about any Google API. Although this is nice, I could not find the API I was looking for. In this case, it seems that information about Google contacts is missing, even though an API for managing contacts does exist.

Google Apps documentation

After some more searching I stumbled upon this documentation page about the contacts API. This page has detailed information about how to use this API which is great. However, any information on how to use this API with just javascript is lacking. After more looking around I found a page which does describe on how to do this with javascript but this version is deprecated.

Google javascript API library

Google has a nice javascript library for using many Google APIs. The basic flow on using this library is as follows:

  1. Load the library
  2. Set the API key
  3. Set the scopes
  4. Set the client ID
  5. Call an authentication method to get an access token
  6. Load an API with an http request
  7. Call the API

In the first 4 steps I did not run into any issues. However, when trying to load the contacts API, the server responded that it did not exist.

gapi.client.load('contacts', 'v3');

/*
which results in the following error:

GET https://content.googleapis.com/discovery/v1/apis/contacts/v3/rest?fields=rootUrl%2CservicePath%2Cresources%2Cparameters%2Cmethods&pp=0 404 (Not Found)
*/

Loading any other API that was listed in the API explorer was no problem though as loading the urlshortener did not result in an error.

gapi.client.load('urlshortener', 'v1')

This made me think that the javascript library for the contacts just did not exist. After more searching I found out that it indeed does not exist in this Stack Overflow issue http://stackoverflow.com/questions/20017487/getting-google-contacts-with-javascript.

Solution

Approach

The approach to our solution, which is also described in the Stack Overflow issue, turns out to be pretty simple. When you have an access token, it is possible to call any API with a simple http request, eliminating the need of a specific JavaScript library that wraps this process. The process of retrieving an access token remains the same:

1. Load the library
2. Set the API key
3. Set the scopes
4. Set the client ID
5. Call an authentication method to get an access token

Now, instead of using the gapi library, use this access token to call the API.

6. Call the API using an http request with the access token retrieved

For example, to retrieve the contacts of our user (I used the get method from jQuery):

		$.get("https://www.google.com/m8/feeds/contacts/default/thin?alt=json&access_token=" + authResult.access_token + "&max-results=700&v=3.0")
	

7. Process the results to serve the information you need.

I do recommend to use the library whenever possible as this will reduce the amount of boilerplate code you have to write.

Code example

As a result, this code snippet will provide you with the contacts of a user. To serve this file, I used a simple python command to start an http server in the correct directory with:

python -m SimpleHTTPServer

When running this example, check the console’s log to see the result. For Magnet.me we changed this to an implementation with AngularJS but the approach remains the same.