Performance Tips

This document covers some techniques you can use to improve the performance of your application. In some cases, examples from other APIs or generic APIs are used to illustrate the ideas presented. However, the same concepts are applicable to the Google Analytics API.

Using gzip

An easy and convenient way to reduce the bandwidth needed for each request is to enable gzip compression. Although this requires additional CPU time to uncompress the results, the trade-off with network costs usually makes it very worthwhile.

In order to receive a gzip-encoded response you must do two things: Set an Accept-Encoding header, and modify your user agent to contain the string gzip. Here is an example of properly formed HTTP headers for enabling gzip compression:

Accept-Encoding: gzip
User-Agent: my program (gzip)

Working with partial resources

Another way to improve the performance of your API calls is by requesting only the portion of the data that you're interested in. This lets your application avoid transferring, parsing, and storing unneeded fields, so it can use resources including network, CPU, and memory more efficiently.

Partial response

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 response data.

Example

The following example shows the use of the fields parameter with a generic (fictional) "Demo" API.

Simple request: This HTTP GET request omits the fields parameter and returns the full resource.

https://www.googleapis.com/demo/v1?key=YOUR-API-KEY

Full resource response: A request that returns the full resource data includes the following fields, along with many others that have been omitted for brevity.

<?xml version="1.0" encoding="UTF-8"?>
<feed gd:kind="demo"
    xmlns="http://www.w3.org/2005/Atom"
    xmlns:gd="http://schemas.google.com/g/2005">
  <title type="html">Demo title</title>
  <id>tag:www.googleapis.com,2010-09-29:/demo/v1</id>
  <author>
    <name>Demo Author</name>
  </author>
  <updated>2011-06-10T23:55:55.133Z</updated>
  ...
  <entry>
    <id>324</id>
    ...
  <title type="html">First title</title>
    <comment>First comment</comment>
    <characteristics>
      <length>short</length>
      <accuracy>high</accuracy>
      <followers>Jo</followers>
      <followers>Will</followers>
    </characteristics>
    <status>active</status>
    ...
  </entry>
  <entry>
    <id>325</id>
    <...
  <title type="html">Second title</title>
    <comment>Second comment</comment>
    <characteristics>
      <length>long</length>
      <accuracy>medium</accuracy>
      <followers></followers>
    </characteristics>
    <status>active</status>
    ...
  </entry>
  ...
</feed>

Request for a partial response: The following request for this same resource uses the fields parameter to significantly reduce the amount of data returned:

https://www.googleapis.com/demo/v1?key=YOUR-API-KEY&fields=@gd:kind,entry(title,characteristics/length)

Partial response: In response to the request above, the server sends back a response feed that contains only the gd:kind attribute of the feed and pared-down <entry> elements that contain only the title and length characteristic information.

200 OK

<?xml version="1.0" encoding="UTF-8"?>
<feed gd:kind="demo">
  <entry>
  <title type="html">First title</title>
    <characteristics>
      <length>short</length>
    </characteristics>
  </entry>
  <entry>
  <title type="html">Second title</title>
    <characteristics>
      <length>long</length>
    </characteristics>
  </entry>
  ...
</feed>

Note that the response includes only the selected fields, along with the enclosing tags for any parent elements.

Details on how to format the fields parameter is covered next, followed by more details about what exactly 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, and 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.
  • Use "@" prefix to identify a field that is an attribute with the given name; omit the "@" prefix to refer to a field that is an element.
  • Use a sub-selector to request a set of specific attributes or sub-elements by placing expressions in parentheses "( )".

    For example: fields=entry(id,author/email) returns only the entry ID and author's email for each feed entry. You can also specify a single sub-field, where fields=entry(id) is equivalent to fields=entry/id.

  • Use wildcards in field selections, if needed.

    For example: fields=entry/gd:* selects all child elements of entry in the gd namespace, and entry/@gd:* selects child element attributes in the same namespace.

    Note: Namespace aliases cannot be changed; matches for partial responses are done against the qualified field names as they appear in the full response.

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.

Identify the fields you want returned, or make field selections.
The fields request parameter value is a comma-separated list of elements or attributes (collectively called fields), and each field is specified relative to the root element of the resource representation. Thus, if you are retrieving a feed, fields are specified relative to the <feed> element, and if you are retrieving a single entry, fields are specified relative to the <entry> element. If the element you select is (or is part of) a repeating element in the feed, the server returns all instances of that element.

Here are some feed-level examples:
Examples Effect
entry Returns all <entry> elements and all attributes and sub-elements of those entries, but not any other child elements of <feed>.
id,entry Returns both the feed <id> and all <entry> elements.
entry/title Returns the <title> element for all feed entries.

Whenever a nested element is returned, the response includes enclosing tags for any parent elements. The parent tags do not include any other child elements or attributes unless they are also selected explicitly.
entry/link/@rel Returns only the rel attribute of the <link> element for all feed entries.
entry/*:rating Returns only sub-elements with local name rating in any namespace for all feed entries.

Here are some entry-level examples:
Examples Effect
author Returns the <author> child element of the target entry.
@gd:etag Returns the etag attribute of the target entry.
author/uri Returns the <uri> sub-element of the <author> element for the target entry.
media:group/media:* Returns all sub-fields of <media:group> in the media namespace for the target entry.
Request only parts of specific fields using sub-selections.
By default, if your request specifies particular elements, the server returns the elements in their entirety. You can specify a response that includes only certain sub-elements or attributes. You do this using "( )" sub-selection syntax, as in the examples below.
Examples Effect
entry(link(@rel,@href)) Returns only the values of the rel and href attributes for each <link> element in feed entries.
entry(title,author/uri) Returns both <title type="html"> elements and author <uri> elements for each feed entry.

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").

Here is the partial response example shown in the introductory section above. The request uses the fields parameter to specify which fields to return.

https://www.googleapis.com/demo/v1?key=YOUR-API-KEY&fields=@gd:kind,entry(title,characteristics/length)

The partial response looks like this:

200 OK

<?xml version="1.0" encoding="UTF-8"?>
<feed gd:kind="demo">
  <entry>
  <title type="html">First title</title>
    <characteristics>
      <length>short</length>
    </characteristics>
  </entry>
  <entry>
  <title type="html">Second title</title>
    <characteristics>
      <length>long</length>
    </characteristics>
  </entry>
  ...
</feed>

Note: For APIs that support query parameters for data pagination (maxResults and nextPageToken, for example), use those parameters to reduce the results of each query to a manageable size. Otherwise, the performance gains possible with partial response might not be realized.