Google has announced that the Google Contacts API is officially deprecated and will sunset on June 15, 2021. This means that if you’ve built an integration with the Google Contacts API, you will need to find a new solution to access data from your user’s Google Contacts account. Fortunately for Nylas customers, we’ve been well aware of Google’s intention to deprecate this service for some time, and developers who use the Nylas Contacts API will have uninterrupted access to Google Contacts with no additional effort necessary on their part.
This article is for anyone who currently has, or is considering integrating Google Contacts information into their app, and what the transition to the Google People API means for you.
What is the Google Contacts API?
The Google Contacts API is an older XML API that provides access to a Google GData Contact Kind object. This object is part of the Google Data API and was also formerly used to represent things like businesses and organizations for use in places like Google Maps. Google has been slowly deprecating everything that uses the Google Data API in recent years as they migrate to more modern APIs for their services. So, it comes at no surprise that they’ve set an official end to the Google Contacts API.
With that said, the Google Contacts API supported many features that, until recently, weren’t supported by the People API. Specifically, Google Contacts has an “Other Contacts” label that generates a list of contacts the user has as a result of other Google product interactions. For example, this list includes the name and email for any people the user has had an email interaction with via Gmail; you can see your own list on the Google Contacts website. Google has since added a method to the People API that exposes this list, paving the way for them to fully sunset the People API.
What is the Google People API?
The Google People API is a much newer product that follows modern REST conventions. Its original purpose was to merge identities from multiple Google products, like Google Contacts, Gmail, Google+, and Google user profiles, to provide a single API that makes all of them available. This follows the conventions that other companies like Microsoft are doing with their similarly named People API.
If you’re only interested in migrating from the Google Contacts API to the People API, you can check out the migration guide Google has put together for this purpose. There are quite a few fields that have either been deprecated or changed, so make sure to take a close look to see if your integration will be affected.
How to Use the Google People API
Since Google officially wants developers to use the Google People API to access user contacts, let’s take a look at how to read and create contacts with it.
Parse Contact Info
The Google People API has three separate processes for returning contacts depending on what type of contact the person is: Directory Contacts, Connections, and Other Contacts. Let’s take a look at these one-by-one.
Directory contacts are people who exist inside the user’s GSuite organization. The people.listDirectoryPeople method is used to request directory contacts, and it requires you to specify a directory source type and a readMask, which is a type of FieldMask, that specifies which data fields should be returned in the response such as names, emails, addresses, and more. This method will return a JSON list that includes all of the requested data for each contact.
Connections are people the user manually has added to one more Google products like Google Contacts, and these can have custom, user-created labels. The people.connections.list method can be used to return data for this type of contact, and it requires you to provide a resourceName of “people/me” and a personFields parameter that specifies the data you want to return (similar to the readMask parameter for directory contacts).
Other contacts is a list that is automatically generated by user interactions with Google products that has a limited amount of contact information. For example, this list includes the name and email for any contacts the user has exchanged an email with via Gmail. The otherContacts.list method is used to return contacts from this list, and it requires you to provide a readMask attribute that contains one or more of emailAddresses, names, or phoneNumbers.
How to Create a Contact via the Google People API
The Google People API offers two options to create contacts. The standard way is with the people.createContact method. When invoked, you can define a wide range of details for the contact, such as their name, email address, phone number, job title, and more. This is functionally the same as the user logging into their Google Contacts account and adding the information manually.
Alternatively, you can also copy a contact directly from the Other Contacts list to the primary contacts list with the otherContacts.copyOtherContactToMyContactsGroup function. It requires you to specify one or more attributes to copy from the other contacts resource: names, emailAddresses, or phoneNumbers. This can be useful if you want to add data to an other contact beyond their name, email address, and phone number.
Let Nylas Handle Third Party Integrations For You
Even though the Google Contacts API deprecation has been a long time coming, it’s still disruptive when underlying technologies that power your product experience major changes because it forces you to take valuable time away from building the features your users love. If you need to integrate Google Contacts into your app, and you’re considering a direct integration with the Google People API, you should take a moment to evaluate if this fits your long term software development needs.
An alternative solution is the Nylas Contacts API, which provides a simple REST API that reduces the complexity of integrating Google Contact data and functionality into your app. Let’s look at some of the benefits Nylas provides to developers.
One Method to Rule Them All
Create, read, update, destroy, these are the fundamental methods that can be performed on any piece of data. Unfortunately, it’s not so straight forward with the Google People API, which has three separate methods for accessing a user’s contact book and two methods for creating contacts that each have their own unique requirement for accessing and manipulating data. If you’re building sophisticated features like contact auto-recommendation, search, or display, you need accurate contact information at a moments notice to provide the best user experience. Searching across three separate locations for data in a user’s contact book takes precious time and bandwidth.
With Nylas, you get a single point of integration via the Contacts API, which provides a standard interface for interacting with Google Contacts. Nylas abstracts away the complexity of dealing with the different types of contact information that’s exposed via the Google People API and presents you with a predictable REST interface that uses JSON to provide consistent representations of a user’s contacts.
Here’s an example of a Google Contact returned via the Nylas Contacts API:
{
"given_name": "Ada",
"surname": "Lovelace",
"job_title": "Senior Researcher",
"birthday": "1925-12-10",
"company_name": "Algo Prime",
"emails": [
{
"email": "ada@algoprime.com",
"type": "work"
}
],
"phone_numbers": [
{
"number": "1 112 718 5236",
"type": "business"
}
],
"groups": [
{
"id": "a0a0a0a0a0a0a0a0a0a0a0",
"object": "contact_group",
"account_id": "x2x2x2x2x2x2x2x2x2x2x2",
"name": "Work",
"path": "Contacts/Work"
}
],
... # This example has been abbreviated for readability
}
Here’s an example of how to create a Google Contact via the Nylas Contacts API:
curl -X POST 'https://api.nylas.com/contacts' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-d '{
"given_name": "Leonardo",
"surname": "Da Vinci",
"company_name": "Ornitech Unlimited",
"job_title": "Flight Architect",
"emails": [
{
"type": "work",
"email": "leo@ornitech.com"
}
]
}'
The Google People API Lacks a Notification System
Many of Google’s API services offer some sort of notification system that will inform your app whenever updates happen to the connected user account. Unfortunately, the Google People API has no such service, meaning that if you want to keep an up-to-date picture of your user’s contact book, you’ll need to build your own local copy of the user’s contact data and regularly poll the People API to compare the returned data with your local version. You’ll also have to write code that reconciles any conflicts between these two versions. This seemingly small gap in API functionality can quickly add up in development time.
Alternatively, Nylas provides webhooks that can be configured to automatically notify your app whenever a user’s contacts are created, updated, or deleted. This lets you spend less time dealing with complex sync issues, and more time building awesome functionality that leverage’s your users’ contact books.
Take Your Google Contacts Integration Further With Nylas
Nylas provides a secure, reliable, and performant integration with Google Contacts, and we protect our developers from changes like the sunset of the Google Contacts API. Not to mention, the Nylas Communications Platform lets you build functionality that extends beyond a user’s contact book to incorporate full email and calendar functionality. Learn how you can use the Nylas Email API to add full email interactivity including threaded email views, draft and send functionality, and label and status management. Or, take a look at how you can leverage the Nylas Calendar API to turn your app into a scheduling powerhouse. Ready to start building? Sign up for a free account today!
Calendar management
Embedded contextual email
Scheduling automation
Automated outreach
Telehealth
Marketplaces
Recruiting
Document management
Real estate
Communications software
Docs
SDKs
Tutorials
API status
Changelog
Support
Blog
Events
Guides
Newsroom
Partners
Build vs. buy
Customer stories
Trust & security
Why Nylas
