Contact Importing

Showdown: Google Contacts API versus Google People API

Don’t Abandon the Google Contacts API quite yet.

May 21, 2021 Update: Our stance has changed on this topic. Google resolved the main drawback which was the inability to get the “Other Contacts” from the People API. And now they are sunsetting the Contacts API.

So we are all in on the People API. You can read about how we’re supporting our customer’s migration here.

Spring Cleaning can Wait…for now.

Spring is here, and we’re all looking for ways to grow and embrace the newest and freshest innovations in all areas of our life. With the Stay-At-Home rules in place for a lot of the United States, we have a lot of time to work on new projects. For Developers, this means a lot of time to build out the new apps or adding new features to optimize for your customers. However, when you’re doing these upgrades to freshen up the look and functionality, you’re not going to want to toss out the Google Contacts API in favour of the newer Google People API…at least not quite yet.

CloudSponge has a long lifetime of integration with the Google Contacts API (going way back to Portable Contacts and OAuth1.0), so it’s vital that we stay abreast of all the changes and updates. We stay up to date on all of the most recent upgrades to stay on the cutting edge of functionality for our clients. There’s been a lot of discussion and speculation by developers as to what Google is planning to do next. What is their next big innovation in our arena? Is Google’s Contacts API on the way out, and if so…what’s taking its place?

In case you haven’t been keeping up with the news on the Google Contacts API, here is a quick refresher. Over the past couple of years, Google has posted that they intend to deprecate the Contacts API. This deprecation will necessitate a move toward its more modern relative, the Google People API. With that in mind, developers want to know when this change is going to take place, and what differences can be expected.

Find out how to make your customers recommend your business to their contacts,

Download The Better Sharing Workbook to learn more

Contacts VS. People

In the Ring…the reigning champ “Contacts,” versus the challenger “People!” Well, it may not be that much of a prizefight at “Contacts” age, but instead a boosting of a newer and more developer-friendly API. The official name, “Google’s People API,” is meant to sound broad and fully encapsulating of a user’s contacts. It’s named as such because this broad-spectrum functionality is the main goal of the new API. Google’s People API is intended to make the comprehensive gathering of all the people with whom a user interacts a very intuitive, seamless, and simple process.

A transitional pattern very similar to this can be seen on Microsoft, which has an API called “People” as well. Perhaps not coincidentally, they also have two APIs just like Google…and their People API takes the innovative leap into bringing in identities from a vast array of locations that are relevant to the user.

This all sounds great…right? Why not switch over to Google’s People right away?

Unfortunately, Google’s People has not yet been able to deliver on the promises that it’s making. Although there are dreams of grandeur, the functionality of the API just isn’t there yet. That’s probably why Google is keeping their Contacts API rolling and will hopefully continue to support it until People has been further developed.

Google is still suggesting that Contacts will be deprecated sometime in the near future, but they haven’t set a date on that so far. As such, we are not in any imminent danger of losing access to the Contacts API.

Just for peace of mind, Google is pretty good at giving everyone a “heads up” when any major change is coming down the pipeline.

So…what actually qualifies as a “Contact” in these APIs?

Some of you might be curious about what exactly constitutes a contact? In the universe we’ve been talking about, the details of parameters become important in relation to how the API works. So is a contact somebody that I’ve communicated with? Does that mean that they’ve emailed me or I’ve emailed them? Have we had at least one back and forth?

The criterion is quite simple. According to Google’s help, “Other contacts” is where (among a couple of edge-cases) Google automatically creates a contact when you send them a message. They do this to enable auto-complete on the email address for future email composition. So basically this means that the entity to which you send any email becomes a contact.

The umbrella under which entities are deemed a contact is quite expansive. It includes everyone you’ve emailed in at least the past seven years.

There’s been some discussion about the potential for malicious contact “adds.” This is basically the idea that someone could add themselves to your contact list just by emailing you. However, this is very unlikely. Without a user sending or replying to an email, it won’t be captured as a contact.

How are these APIs Meeting the User’s Expectations?

There is some good news about these two APIs. They are both flexible in that the configuration in Google Cloud Platform / Google Developer Console / Google APIs Console (or whatever they are currently calling it) doesn’t need to change between these APIs. In addition, when you have Google verify your app to use one of these APIs, it also applies to the other. So basically, the Google scopes are the same.

The purpose of the transition to Google’s People API is to ultimately optimize the user experience and to simplify the process of collecting and transferring Contacts between platforms. Contacts is the older of the two, and when it was first created it embraced XML. It’s been through a number of versions, but each version continues to have the XML payload. It will return data in a JSON format, but the names of fields makes it quite obvious that it’s just poorly translated from XML. It’s a bit awkward when you’re digesting that payload, even though it’s in a JSON format.

Your code is looking for strangely named entities to get the data you want. It’s just not as intuitive in terms of breaking down the payload.

In case you’re a nerd for the details like we are, here is a good concrete example:

XML nodes have zero or more attributes as well as a text value. The literal JSON translation of this nests every value inside a $t property. Also, the JSON includes some XML namespaces in the property names so we get oddly named properties.

E.g. one wonky-looking value is: {"openSearch$totalResults": {"$t": 10}}

The big advantage to the Contacts API, and the reason we use it, is because it doesn’t just include contacts that users have specifically added to their address book, which is where the People API ends. If you go into your Google Contacts account, which used to be part of Gmail, there is the contact item. You go to the nine squares and pick Contacts, and then open up Google Contacts. What you see is just the list of contacts that you’ve added, which is everything that the People API exposes…

Image of my 5 contacts.
It’s lonely in here with only 2 other actual humans.

Now, click on the Other Contacts group in the sidebar. Woah! This is where all the automatically added contacts end up. And it’s in this group where we usually find contacts as we type into the To: field when composing a new email, which is everything that the Contacts API exposes…

Image of my Google Other Contacts containing 821 contacts.
That’s better, I do have friends.

The Contacts API is like the analog, from an API perspective to that user experience. That’s why we use it. We want our contact picker to align with people’s expectations. They go to Gmail, and they see their commonly accessed email addresses in To: fields as they type. When they connect their Gmail account or their Google Contacts account, we want them to see those same email addresses.

Conversely, the People API doesn’t access any of that stuff.

For Now…We’re sticking with Google Contacts

Contacts API is here to stay (despite Google’s indications of otherwise) until the People API is updated to align with the Gmail UX. Once they do formally deprecate the Contacts API, you can be sure they will give plenty of notice.

You can safely ignore this material if you are a CloudSponge customer since we monitor the APIs for changes and we’ll make the changes on our side.

Our sharing optimisations bring in double the number of leads for our clients, each month.

Try for yourself and find out what you're missing

(it's quick, easy and absolutely free!)

Graeme Rouse, CTO at CloudSponge

Follow @thunderouse


Try CloudSponge for free in your
testing environment

Get Started

Have a questions or prefer a guided tour?
Schedule a consultation with our Founder.