How do you use query parameters to limit retrieved contacts in the Google Contacts API

Question

I'm trying to test out the Google Contacts API with JavaScript. I know that V1 had support for JavaScript but V2 and V3 don't list it. However, I have been able to find a way to retrieve contacts through an AJAX request so getting the contacts isn't really the problem right now. However, I'd like to be able to specify the search criteria of the contact that I'm looking for so that I don't have to page and search through all of the users contacts.

Right now, my code looks like this:

function getContact(domTarget) {
   // Get permission and a token
   auth(function(token) {

      // Create an AJAX request to get the contacts
      var ajaxContactRequest = new XMLHttpRequest(),
              url = "";

      // What to do when we get our contacts
      ajaxContactRequest.onreadystatechange = function() {
         if (ajaxContactRequest.readyState === 4 && ajaxContactRequest.status === 200) {

            // Parse our contact data as a JSON object
            var response = JSON.parse(ajaxContactRequest.responseText),
                    contactArray = response.feed.entry, i, contactDiv;

            // Print out the contacts
            if (domTarget) {
               for (i = 0; i < contactArray.length; i++) {
                  if (contactArray[i].title && contactArray[i].title.$t) {
                     contactDiv = document.createElement("div");
                     domTarget.appendChild(contactDiv);

                     // Print out the contact's name
                     contactDiv.innerHTML = contactArray[i].title.$t;
                  }
               }
            }
         }
      };

      // Construct our URL
      url += "https://www.google.com/m8/feeds/contacts/default/full/";
      // Add the access token
      url += "?access_token=" + token.access_token;
      // Get JSON format back
      url += "&alt=json";
      // Limit to 10 results
      url += "&max-results=10";

      // Open the request
      ajaxContactRequest.open("GET", url, false);

      // Send it away
      ajaxContactRequest.send();
   });
}

I know that there is some sort of support for queries because the listing here: Retrieving Contacts Using Query Parameters mentions that you can use the parameters found here: Contacts Query Parameters Reference which lists q=term1 term2 term 3 and `q="term1 term2 term3" are the way to do "Fulltext query on contacts data fields".

I have tried several different mixes of parameters such as first and last name as well as dates and emails. However, none of them have any impact on the results. Another thing that I am wondering is if this really matters. I'm limiting my query based on name only to try and reduce the size of the response. However, if the better practice is to just grab the whole contact set and then glean the bits of info that you need, I guess I can do that instead.

I figure you have to do multiple requests if the number of contacts is larger than the max-results size.

Answer 1

You need to switch to version 3 of Google Contacts API.

v1 and v2 don't have support for the "search term" (q) parameter, so you're limited to query parameters like "last updated" and "order by" and such.

So. First off they hint that all of your headers need the "GData-Version: 3.0" parameter. https://developers.google.com/google-apps/contacts/v3/#specifying_a_version

If you're using jQuery, that's fairly straightforward. Here's an example: Set Request Header jQuery Ajax

But in the code you've got already, you can just add it to the URL for all requests.

url += "https://www.google.com/m8/feeds/contacts/default/full/?v=3";

(again in jQuery, it's easy to add it as a param too if modifying the header is scary)

The kicker, and it took me weeks to figure this out, is that the "scope" itself is wrong.

In your HTML code I'm sure you've authorized your app using...

scope="https://www.google.com/m8/feeds"

... as it says to do in the documentation. But when they say "all requests need the header" they really mean ALL requests. And if you're using Google's pre-canned HTML examples to authorize your application, then you simply don't have access to the code which would let you modify the headers. So instead you need to use...

scope="https://www.google.com/m8/feeds?v=3"

This is because the v2 API and v3 API share a scope URL, which you really only notice if you're reading the v2.0 and the v3.0 documentation side by side.

Anyway, I hope that helps.

Kieron