Announcing the People API

We’re delighted to announce the availability of the People API. With it, you can retrieve data about an authenticated user’s connections from their Contacts. Previously, developers had to make multiple calls to the Google+ API for user profiles and the Contacts API for contacts. The new People API uses the newest protocols and technologies and will eventually replace the Contacts API which uses the GData protocol.

For example, if your user has contacts in her private contact list, a call to the API (if she provides consent to do so) will retrieve a list containing the contacts merged with any linked profiles. If the user grants the relevant scopes, the results are returned as a people.connections.list object. Each person object in this list will have a resourceName property, which can be used to get additional data about that person with a call to people.get.

The API is built on HTTP and JSON, so any standard HTTP client can send requests to it and parse the response. However, applications need to be authorized to access the APIs so you will need to create a project on the Google Developers Console in order to get the credentials you need to access the service. All the steps to do so are here. If you’re new to the Google APIs and/or the Developers Console, check out this first in a series of videos to help you get up-to-speed.

Once you’re connected and authorized, you can then get the user’s connections like this (using the Google APIs Client Library for Java):

 ListConnectionsResponse response =   
     peopleService.people().connections().list("people/me").execute();  
 List<Person> connections = response.getConnections();  

Full documentation on the people.connections.list method is available here.

The list of connections will have details on all the user’s social connections if the required scopes have been granted. Contacts will only be returned if the user granted a contacts scope.

Each Person item will have a resource_name associated with it, so additional data for that person will be accessible via a simple call:

Person person = peopleService.people().get("resourceName").execute();

Details on this API call can be found here.

In addition to merging data from multiple sources and APIs into a single cohesive data source, the new People API also exposes additional data that was not possible to get before, such as private addresses, phone numbers, e-mails, and birthdays for a user who has given permission.

We hope that these new features and data along with simplified access to existing data inspires 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.