Posted by Ting Huang, Software Engineer
Some time ago, we announced that the Google Contacts API was being deprecated in favor of the People API, and it is scheduled for sunset on June 15, 2021. To aid in the process of migrating from Contacts API, we are pleased to announce that we have added two sets of new endpoints for working with contacts via the People API.
First, we now have new write endpoints that allow developers to create, delete, and update multiple contacts at once. In addition, we also have new read endpoints that allow developers to search a user’s contacts using a prefix query. Both will greatly improve working with the People API, so let’s take a quick look at how you can leverage these new endpoints today.
Getting Started with the People API
Applications need to be authorized to access the API, so to get started you will need to create a project on the Google Developers Console with the People API enabled to get access to the service. If you are new to the Google APIs, you can follow the steps here to begin accessing People API.
Working with Batch Mutate Endpoints
Once you’re authorized, you can simply create new contacts like this (using the Google APIs Client Library for Java):
Person person = new Person();
person.setNames(ImmutableList.of(new
Name().setGivenName("John").setFamilyName("Doe")));
ContactToCreate contactToCreate = new ContactToCreate();
contactToCreate.setContactPerson(person);
BatchCreateContactsRequest request = new BatchCreateContactsRequest();
request.setContacts(ImmutableList.of(contactToCreate)).setReadMask("names");
BatchCreateContactsResponse response =
peopleService.people().batchCreateContacts(request).execute();
The scope your app needs to authorize with is https://www.googleapis.com/auth/contacts. Full documentation on the people.batchCreateContacts method is available here.
Similarly, you can update existing contacts like this:
String resourceName = "people/c12345"; // existing contact resource name
Person contactToUpdate =
peopleService
.people()
.get(resourceName)
.setPersonFields("names,emailAddresses")
.execute();
contactToUpdate.setNames(
ImmutableList.of(new Name().setGivenName("John").setFamilyName("Doe")));
BatchUpdateContactsRequest request = new BatchUpdateContactsRequest();
ImmutableMap<String, Person> map =
ImmutableMap.of(contactToUpdate.getResourceName(), contactToUpdate);
request.setContacts(map).setUpdateMask("names")
.setReadMask("names,emailAddresses");
BatchUpdateContactsResponse response =
peopleService.people().batchUpdateContacts(request).execute();
Full documentation on the people.batchUpdateContacts method is available here.
Working with Search Endpoints
You can search through the authenticated user’s contacts like this:
SearchResponse response = peopleService.people().searchContacts()
.setQuery("query")
.setReadMask("names,emailAddresses")
.execute();
The scope your app needs to authorize with is https://www.googleapis.com/auth/contacts or https://www.googleapis.com/auth/contacts.readonly. Full documentation on the people.searchContacts method is available here.
You can also search through the authenticated user’s “other contacts” like this:
SearchResponse response = peopleService.otherContacts().search()
.setQuery("query")
.setReadMask("names,emailAddresses")
.execute();
The scope your app needs to authorize with is https://www.googleapis.com/auth/contacts.other.readonly. Full documentation on the otherContacts.search method is available here.
Next Steps
We hope that these newly added features inspire you to create the next generation of cool web and mobile apps that delight your users and those in their circles of influence. To learn more about the People API, check out the official documentation here.