Announcement: new features, changes, and the v4 API upgrade
Philip Walton
Users of the Google Analytics add-on have by now likely noticed it got a recent upgrade. The primary reason for the upgrade was to migrate the add-on from using the legacy Core Reporting API (v3) to the Analytics Reporting API (v4).
In addition, the add-on now supports several new features that users have been asking for. This post summarizes all the change. For a complete reference of all the new features, see the reference documentation. And as always, if you have any issue, please report them here.
New Features
Multiple segments
You can now get multiple segments in the same report. When more than one segment is specified, the left-most column of the report will show the segment name. Refer to the segments section of the documentation for usage instructions.
Unlimited rows in a single report
The old version of the add-on enforced the v3 API maximum of 10,000 rows per report. The v4 API maximum is 100,000 rows per report, but to make it easier to work with large reports, the add-on now supports even higher limits or unlimited report sizes by not setting a value for the Limit parameter.
Note: for reports with more than 100,000 results, the add-on will make additional requests until the limit is reached or all results are returned. These additional requests will count toward your quota, so be careful when using this feature. These reports will also take longer to run, which in some cases can lead to timeout errors if you have lots of large reports. Lastly, Google Sheets imposes a limit on the number of cells that can be in a single spreadsheet, and this add-on cannot bypass that limit.
Better sampling
The Reporting API v4 has the same sampling rates as Google Analytics itself. In addition, Google Analytics 360 (Premium) customers can set the Use Resource Quotas parameter to get much higher sampling thresholds (up to 100 million sessions) where applicable.
Calculated metrics expressions
The Reporting API v4 supports metric expressions, which can be used to define calculated metrics on the fly, or programmatically using Sheet's functions. Refer to the metrics section of the documentation for usage instructions.
Other changes
In addition to the above new features, some features have been removed or their behavior has slightly changed. If you're experiencing any issues with the upgrade, please check this list before reporting errors.
The "Last N Days" parameter has been removed
Now that the API supports relative date keywords like "yesterday" and "30daysAgo", the "Last N Days" parameter has been removed. In addition, the "Last N Days" parameter was causing confusion as to whether the date range included the current day or not. Users are encouraged to use either these relative keywords or Sheet's date functions.
Space separators between values is no longer supported
Users who had spaces separating multiple values in their Report Configuration sheet are now seeing errors after the upgrade. The fix for this is to use either commas or newlines to separate multiple values. Refer to the documentation for complete formatting guidelines.
Note: the use of spaces as value separators was never supported (even though it worked in the previous add-on version), and unfortunately that behavior cannot be restored because it leads to ambiguous cases in filters where the dimension name contains spaces, e.g: ga:city==New York.
The "Start Index" parameter has been removed
Now that the Limit parameter supports unlimited results, the "Start Index" parameter is no longer very useful. As a result, it's been removed.