Google+ API

API

View the Google+ API reference overview with resources People, Activities, and Comments.

Note: The Google+ API currently provides read-only access to public data. All API calls require either an OAuth 2.0 token or an API key.

Quota

Your application is limited to the number of API calls it can make by a usage courtesy quota. To view the courtesy limit and to request additional quota for your application, in the Google API Console, choose Quotas from the left menu for your project. On that page are two groups of API calls:

• Google+ API (Sign-in) - For methods that are allowed by the scope https://www.googleapis.com/auth/plus.login (people.get, and people.list).
• Google+ API - For all other methods.

Each group has its own limit, which applies to the total of all API calls in that group.

Authorization

Many API calls require that the user of your application grant permission to access their data. Google uses the OAuth 2.0 protocol to allow authorized applications to access user data. To learn more, see OAuth.

API Calls

Most of the Google+ API follows a RESTful API design, meaning that you use standard HTTP methods to retrieve and manipulate resources. For example, to get the profile of a user, you might send an HTTP request like:

GET https://www.googleapis.com/plus/v1/people/userId

Data Formats

Resources in the Google+ API are represented using JSON data formats. For example, retrieving a user's profile may result in a response like:

{
  "kind": "plus#person",
  "id": "118051310819094153327",
  "displayName": "Chirag Shah",
  "url": "https://plus.google.com/118051310819094153327",
  "image": {
    "url": "https://lh5.googleusercontent.com/-XnZDEoiF09Y/AAAAAAAAAAI/AAAAAAAAYCI/7fow4a2UTMU/photo.jpg"
  }
}

Pagination

In requests that can respond with potentially large collections, such as the collection returned by activities.list, each response contains a limited number of items set by maxResults (default: 20). Each response also contains a nextPageToken property. To obtain the next page of items, you pass this value of nextPageToken to the pageToken property of the next request. Repeat this process to page through the full collection. For the last page, nextPageToken will be absent.

Note: Page tokens become stale over time — if new items have been added to a list since you started paginating, they might not appear in the results. If you held a pageToken for a long period of time and want to continue paging, it might be better to restart pagination by repeating the original request by omitting the pageToken.

For an example of pagination, calling an activities.list method returns a response with nextPageToken:

{
  "kind": "plus#activityFeed",
  "title": "Plus Public Activities Feed",
  "nextPageToken": "CKaEL",
  "items": [
    {
      "kind": "plus#activity",
      "id": "123456789",
      ...
    },
    ...
  ]
  ...
}

To get the next page of activities, pass the value of this token in with your next activities.list request:

https://www.googleapis.com/plus/v1/people/me/activities/public?pageToken=CKaEL

As before, the response to this request includes nextPageToken, which you can pass in to get the next page of results. You can continue this cycle to get new pages.

Partial Responses

By default, the server sends back the full representation of a resource after processing requests. For better performance, you can ask the server to send only the fields you really need and get a partial response instead.

To request a partial response, use the fields request parameter to specify the fields you want returned. You can use this parameter with any request that returns a response body.

Example

The following example shows the use of the fields parameter with the Google+ API.

Simple request: This HTTP GET request omits the fields parameter and returns the full activity resource, with its dozens of fields.

https://www.googleapis.com/plus/v1/activities/z12gtjhq3qn2xxl2o224exwiqruvtda0i?key=YOUR-API-KEY

Request for a partial response: This HTTP GET request for the above resource that uses the fields parameter significantly reduces the amount of data returned.

https://www.googleapis.com/plus/v1/activities/z12gtjhq3qn2xxl2o224exwiqruvtda0i?fields=url,object(content,attachments/url)&key;=YOUR-API-KEY

In response to the above request, the server sends back a JSON response that contains only the url field and the pared-down object that includes only content and attachments.url.

{
 "url": "https://plus.google.com/102817283354809142195/posts/F97fqZwJESL",
 "object": {
  "content": "A picture... of a space ship... launched from earth 40 years ago.",
  "attachments": [
   {
    "url": "http://apod.nasa.gov/apod/ap110908.html"
   }
  ]
 }
}

Note that the response is a JSON object that includes only the selected fields and their enclosing parent objects.

Syntax of the fields parameter is covered next, followed by more detail about what gets returned in the response.

Fields parameter syntax summary

The format of the fields request parameter value is loosely based on XPath syntax. The supported syntax is summarized below; additional examples are provided in the following section.

• Use a comma-separated list to select multiple fields.
• Use a/b to select a field b that is nested within field a; use a/b/c to select a field c nested within b.
• Specify field sub-selectors to request only specific sub-fields by placing expressions in parentheses "( )" after any selected field.

  For example: fields=items(id,object/content) returns only the item id and object's content, for each items array element.

• Use wildcards in field selections, if needed.

  For example: fields=items/object/* selects all items in an object.

More examples of using the fields parameter

The examples below include descriptions of how the fields parameter value affects the response.

Note: As with all query parameter values, the fields parameter value must be URL encoded. For better readability, the examples in this document omit the encoding.

Field selections: Identify the fields you want returned.

The fields request parameter value is a comma-separated list of fields, and each field is specified relative to the root of the response. Thus, if you are performing a list operation, the response is a collection, and it generally includes an array of resources. If you are performing an operation that returns a single resource, fields are specified relative to that resource. If the field you select is (or is part of) an array, the server returns the selected portion of all elements in the array.

Here are some collection-level examples from activities.list:

Examples	Effect
items	Returns all elements in the items array, including all fields in each element, but no other fields.
updated,items	Returns both the updated field and all elements in the items array.
items/title	Returns only the title field for all elements in the items array. Whenever a nested field is returned, the response includes the enclosing parent objects. The parent fields do not include any other child fields unless they are also selected explicitly.

Here are some resource-level examples from activities:

Examples	Effect
title	Returns the title field of the requested resource.
actor/displayName	Returns the displayName sub-field of the actor object in the requested resource.
object/attachments/url	Returns only the url field for all members of the attachments array, which is itself nested under the object object.

Field sub-selections: Request only parts of the selected elements.

By default, if your request specifies particular objects, the server returns the objects in their entirety. You can specify a response that includes only certain sub-fields within the selected objects. You do this using "( )" sub-selection syntax, as in the example below:

Example	Effect
items(id,url)	Returns only the values of the id and url fields for each element in the items array.

Handling partial responses

After a server processes a valid request that includes the fields query parameter, it sends back an HTTP 200 OK status code, along with the requested data. If the fields query parameter has an error or is otherwise invalid, the server returns an HTTP 400 Bad Request status code, along with an error message telling the user what was wrong with their fields selection, for example, "Invalid field selection a/b".

Note: Whenever possible, use maxResults judiciously to reduce the results of each query to a manageable size. Otherwise, the performance gains possible with partial response might not be realized.