My favorites ▼ | English ▼ | Sign in

Google Analytics

Google Analytics Core Reporting API Changelog

Subscribe Subscribe

We periodically update the Google Analytics Core Reporting API in order to deliver new features and to repair defects discovered in previous versions. In most cases, these changes will be transparent to API developers. However, occasionally we need to make changes that require developers to modify their existing applications.

This page documents any changes made to the Google Analytics Core Reporting API that might affect your application. We recommend that API developers periodically check this list for any new announcements. Changes will also be announced via the Atom feed for this page and in the Google Analytics API notify group.

Release 2012-02 (February 8, 2012)

This release add new site speed metrics to the API.

New Metrics

  • The following site speed metrics have been added:

    • ga:speedMetricsSample
    • ga:domainLookupTime
    • ga:pageDownloadTime
    • ga:redirectionTime
    • ga:serverConnectionTime
    • ga:serverResponseTime
    • ga:avgDomainLookupTime
    • ga:avgPageDownloadTime
    • ga:avgRedirectionTime
    • ga:avgServerConnectionTime
    • ga:avgServerResponseTime

Check the Dimensions and Metrics Reference for definitions.

API Version 2.3 Deprecation Reminder

  • Version 2.3 of the Data Export API has been depreacted for 2 months. In roughly 4 more months we will shut down this service and only support the new Core Reporting API version 3.0 and version 2.4.

  • We highly recommend you migrate your applications to version 3.0.

  • In 4 months requests to the legacy version 2.3 XML data feed will be forwarded to version 2.4 and return a version 2.4 XML response. At that point, all version 2.4 quota policies will apply to the version 2.3 requests.

  • All requests for version 2.3 JSON or the Google Data JavaScript client library that uses version 2.3 JSON output, will return 404 status codes.

  • To get full quota, both version 3.0 and version 2.4 require you to register your application in the Google APIs Console and use an API key (or OAuth 2.0 token) in each request.

Release 2012-01 (January 26, 2012)

We fixed a small bug with ga:visitLength. This dimension now returns correct data.

Release 2011-12 (December 5, 2011)

This release effects all Google Analytics API developers. It announces two new versions of the API, requires applications to register, introduces a new quota policy, and it changes the API name to the Core Reporting API. Finally it deprecates the existing Data Export API version 2.3.

Version 3.0

  • The Core Reporting API version 3.0 is the latest major version of our API and is not backwards compatible. All future development of the API will be done on this version.

  • New Features

    • New JSON based output reduces the size of the response ~10x from the previous XML output.
    • New Google API client libraries that support Java, JavaScript, Python, PHP, Ruby, and .Net.
    • Support for the Google Discovery API.
    • Support for OAuth 2.0 as the new, recommended way to authorize users.

  • Updates

    • New URL to make requests: https://www.googleapis.com/analytics/v3/data/ga....
    • Registration and developers tokens required.
    • All requests for configuration data should be done through the Management API.

Version 2.4

  • The Core Reporting API version 2.4 is a minor version upgrade that is mostly backwards compatible with the existing Data Export API version 2.3.

  • Updates

    • New URL to make requests: https://www.googleapis.com/analytics/v2.4/data...
    • Registration and developers tokens required.
    • XML output consistent with version 2.3, so the other existing Google Data client libraries will continue to work.
    • Error code for quota errors have changed from 503 to 403
    • JSON responses are not supported.
    • Google Data JavaScript client library not supported.
    • No Account Feed. All requests for configuration data should be done through the Management API.

Registration

  • All applications built using the Google Analytics API must be registered as a project through the Google APIs Console.

  • Each request to the API must include either a API key or for OAuth 2.0, a Client Id and Client Secret.

Quota Policy

  • The following quota applies to both Anlaytics APIs (Management API and Data Export API)

    • 50,000 requests per project per day
    • 10 queries per second (QPS) per IP address

  • The following quota applies to the Data Export API

    • 10,000 requests per profile per day
    • 10 concurrent requests per profile

  • For unregistered applications, we provide a very low grace quota to accommodate a small amount of testing.

Deprecations

  • This release also announces the deprecation of Version 2.3 and the upcoming shut down of the Account Feed in the Data Export API. In 6 months:

    • Requests to the version 2.3 XML data feed will be forwarded to version 2.4 and return a version 2.4 response. At that point, all version 2.4 quota policies will apply to the version 2.3 requests.

    • Requests to the version 2.3 JSON output will not be supported by the version 2.4 response and will return 404 Not Found status codes. If you need a JSON response, upgrade to Version 3.0.

    • Requests to the Account Feed in the Data Export API will return 404 Not Found status codes. All requests for configuration data should be done through the Management API.

Release 2011-09 (September 7, 2011)

This release adds fresher AdWords data and more combinations for AdWords dimensions and metrics.

  • AdWords data is now updated within an hour. Before the data was updated daily.

  • We’ve relaxed a number valid combinations restrictions with AdWords data.

A few weeks ago we made a change to disallow API queries that asked for ga:adGroup or ga:adContent with ga:impressions, since this combination returned 0. With this change, this combination is now back and has been fixed to return correct data.

Release 2011-08 (August 11, 2011)

This release fixes some invalid combinations of dimensions and metrics

Fixed invalid metrics/dimensions combinations

  • Last month we announced some upcoming changes to the API to disallow some invalid queries in the data feed that do not return any data. We have now made those changes to the API, and the following combinations are now invalid:

    • Product dimensions cannot be combined with transaction metrics.
    • ga:adContent or ga:adGroup cannot be combined with ga:impressions.

    Instead of returning a response with 0 results, the API now returns 400 error code for all queries that ask for these combinations.

Release 2011-07 (July 11, 2011)

This release deprecates the confidence interval value in metrics.

Deprecation of Confidence Interval

  • If you haven’t already done so, please stop using confidence interval values for metrics. With this release, the Data Export API Data Feed returns 0.0 for all the confidence interval values. In a month or so, we will we will completely remove this attribute from all metric elements.

    To determine if a response has been sampled, please use the containsSampledData field in the response.

Release 2011-05 (May 31, 2011)

This release adds 3 new metrics and updates the return value of two.

New Data Updates

  • We added 3 new metrics dealing with site speed performance to the API:

    • ga:pageLoadSample
    • ga:pageLoadTime
    • ga:avgPageLoadTime

Metric Updates

  • To specify currency values in filters, you must specify the actual value passed in from the tracking code, (e.g. 1 unit will now be specified as 1).

  • ga:CTR now returns the actual percent (e.g. a value of 2% is returned as 2).

Release 2011-04 (April 19, 2011)

This release improves improves Data Feed performance and adds new data:

Performance Improvement

  • This release improves data feed latency by 30 to 35%.

New Data Updates

  • We have updated the list of dimensions and metrics that are allowed in Advanced Segments. Please refer to the updated list to make sure that your requests are valid.

Upcoming Changes

  • Currently, you need to specify a currency filter value as micro units, (e.g 1 unit of currency is specified as 1000000). In the near future, you will need to specify the actual value passed in from the tracking code, (e.g. 1 unit will now be specified as 1).

  • Currently, ga:CTR is a percent and returns the value 0.02. In the near future this will change to return the actual percent (e.g. 2).

Release 2011-03 (March 9, 2011)

This release adds more data to the Data Feed:

New Data Updates

  • The following Time dimension has been added: ga:dayOfWeek

  • The following Internal Search metric has been added: ga:percentVisitsWithSearch

  • The following Event Tracking metrics have been added:

    • ga:visitsWithEvent
    • ga:eventsPerVisitWithEvent

Upcoming Changes

Currently the API returns 401 status codes for for various authorization issues. Within the next couple of weeks, the 401 status will be used exclusively for invalid tokens, giving developers a way to error handle this particular exception.

Release 2011-01 (January 24, 2011)

This release adds significantly more data to the Data Feed:

New Data Updates

  • The calculation of ga:visitors has been changed to return the number of unique visitors across the date range and now supports more dimension and metric combinations.

  • 10 new AdWords dimensions have been added: ga:adDistributionNetwork, ga:adMatchType, ga:adMatchedQuery, ga:adPlacementDomain, ga:adPlacementUrl, ga:adFormat, ga:adTargetingType, ga:adTargetingOption, ga:adDisplayUrl, ga:adDestinationUrl.

  • The metric ga:organicSearches has been added to the campaign group.

  • The metric ga:searchResultViews has been added to the internal site search group.

  • 3 new time-based dimensions have been added: ga:nthDay, ga:nthWeek, ga:nthMonth.

  • The groupings of dimensions and metrics have been changed to better reflect the features they represent.

New Calculated Metrics

The following calculated metrics are derived from calculations using the base metrics. Note: Each name with (n) supports values 1-20.

  • Goal Based: ga:costPerConversion, ga:costPerGoalConversion, ga:costPerTransaction, ga:goal(n)AbandonRate, ga:goal(n)Abandons, ga:goal(n)ConversionRate, ga:goalAbandonRateAll, ga:goalAbandonsAll, ga:goalConversionRateAll, ga:goalValueAllPerSearch, ga:goalValuePerVisit.

  • Content Based: ga:entranceBounceRate, ga:visitBounceRate, ga:entranceRate, ga:exitRate, ga:pageviewsPerVisit, ga:avgTimeOnPage, ga:avgTimeOnSite, ga:avgEventValue.

  • Internal Site Search Based: ga:avgSearchDepth, ga:avgSearchDuration, ga:avgSearchResultViews, ga:searchGoalConversionRateAll, ga:searchGoal(n)ConversionRate, ga:searchExitRate.

  • Ecommerce Based: ga:itemsPerPurchase, ga:margin, ga:percentNewVisits, ga:revenuePerItem, ga:revenuePerTransaction, ga:ROI, ga:RPC, ga:totalValue, ga:transactionRevenuePerVisit, ga:transactionsPerVisit.

Release 2010-11 (November 1, 2010)

This release adds a new feature to the Data Feed:

New Features

  • A new XML element has been added lets users know if the data has been sampled. <dxp:containsSampledData>true</dxp:containsSampledData>. This element will always return whether the data was sampled or not with either true or false. The Java and JavaScript libraries have also been updated with helper methods to access this element.

Release 2010-08 (August 23, 2010)

This release fixes 2 bugs:

Bug Fixes

  • Previously adding an OR operator to a filter expression with a dimension (i.e., ga:keyword==store,ga:keyword==bar) could result in different values than if each filter was applied individually across multiple queries. This has been fixed and using the OR operator now returns consistent values.

  • Some of the API error messages for invalid filters have been updated to NOT include whether it was a dimension or metric filter that caused the error (though the actual offending filter expression will continue to be returned).

Release 2010-07 (July 26, 2010)

This release fixes 3 bugs:

Bug Fixes

  • An encoding issue in the JavaScript Client Library has been fixed. Analytics issue tracker

  • A bug that prevented the Account Feed to not return when a goal name, goal path, goal comparison value, or goal comparison type had been incorrectly set, has now been fixed.

  • It is invalid to OR a dimension and metric in the Data Feed query filter parameter. For example: ga:source==google,ga:visits>5. The error message for this invalid query has been updated to say: Cannot OR dimension filter(s) with metric filter.

Release 2010-05 (May 4, 2010)

This release adds new data and fixes a bug:

New Features

  • The following 5 dimensions have been added in the new category D8. Adwords:

    • ga:adwordsAdGroupId: corresponds to the AdWords API AdGroup.id
    • ga:adwordsCampaignId: corresponds to the AdWords API Campaign.id
    • ga:adwordsCreativeId: corresponds to the AdWords API Ad.id
    • ga:adwordsCriteriaId: corresponds to the AdWords API Criterion.id
    • ga:adwordsCustomerId: cooresponds to the AdWords API AccountInfo.customerId

Bug Fixes

  • We fixed an issue where the Account Feed would not return data if one of the profiles had a misconfigured goal or step.

Release 2010-03 (March 22, 2010)

This release adds a number of new features and fixes a bug:

New Features

  • The iPhone Default Segment (gaid::-11) has been enhanced to now report on all mobile devices. The ID is the same as before (-11), but the name of the segment is now: Mobile Traffic.

  • The sampling rate used by the API is now the same as the web interface. This brings the data for sampled reports inline with the web interface and increases consistency between the two.

  • The quota policy has been updated in an effort to ensure that all users receive equitable access to resources. Please refer to our quota policy documentation for more details. The new policy is:

    • A single web property may make a maximum of 10,000 requests per 24 hours.
    • An application can only make 10 requests in any given 1-second period.
    • An application can only have 4 pending requests at any given time.

  • Some restrictions on dimension and metric combinations have been relaxed. ga:nextPagePath and ga:previousPagePath are now part of the D3. Content group. The D8. Custom Variable group is now called the D6. Custom Variable group. Please see the updated reference guide for these new combinations.

Bug Fixes

  • We fixed a bug on how the API reports the confidenceInterval value for metrics. Previously confidence intervals could have a value of either INF or a number from 0 to 1. Now all confidence intervals will have a value of either INF or a number greater than or equal to 0.

  • ga:itemQuantity and ga:uniquePurchases were previously swapped and returned each other’s value. They are now fixed to return the correct data.

Deprecation of Dimensions and Metrics Reminder

  • If you haven’t done so already, please stop using the previously deprecated dimensions and metrics

Release 2009-12 (December 14, 2009)

This release adds a number of new features:

This release increments the major version number to 2

  • Some features require the use of the latest client libraries. We officially support: Java & Javascript. 3rd party libraries might not be updated yet.

    • Version 2 may be requested by adding the header GData-Version: 2 to each account or data feed request Read the documentation for more details.
    • A new XML namespace has been added to both account and data feeds:
      xmlns:ga='http://schemas.google.com/ga/2009'

  • The API now supports the Google Data protocol version 2.

Advanced segmentation support

  • Dynamic segments query parameter:

    • ...&segment=dynamic::expression
    • allows creation of advanced segments “on the fly.”
    • expression can be any dimension or metric and should follow the same syntax as filters.

  • Default and custom segments query parameter:

    • ...&segment=gaid::number
    • where number is an ID referencing an advanced segment defined in the Google Analytics Web Interface.
    • ID can be found in the account feed.

  • The account feed describes segment data through the following XML elements and attributes:

    • <dxp:segment id='gaid::-3' name='Returning Visitors'>
    • <dxp:definition>ga:visitorType==Returning Visitor</dxp:definition>

  • The data feed also provides an XML element indicating whether a segment was applied in the API request.

  • More details on advanced segments in our documentation.

New goal data available

  • Destination and engagement type goals available in the account feed:

    • <ga:goal active='true' name='Completing Order' number='1' value='10.0'>
    • <ga:destination expression='/purchaseComplete.html' matchType='regex' step1Required='false' caseSensitive='false'>
    • <ga:step number='1' name='Login' path='/login.html'/>
    • <ga:engagement comparison='&gt;' thresholdValue='300' type='timeOnSite'/>

  • 48 new goal metrics have been added for goals 5-20 which all follow the convention goal(n)Completions, where (n) is a number between 1 and 20.

    • ga:goal(n)Completions
    • ga:goal(n)Starts
    • ga:goal(n)Value

  • GoalCompletionAll, GoalStartsAll and GoalValueAll have been updated to account for the new goal data.

New custom variable data

  • All custom variables ever collected by each profile have been added as a new XML element to the account feed:

    • <ga:customVariable index='1' name='category' scope='visitor'>

  • 10 new dimensions have been added for custom variables. They follow the convention customVar(n) where (n) can be a number between 1 and 5.

    • ga:customVarName(n)
    • ga:customVarValue(n)

Deprecated dimensions & metrics to be removed!

  • If you haven’t done so already, please stop using the previously deprecated dimensions and metrics. They will be removed soon and will return errors from our API if requested.

    • ga:countOfVisits
    • ga:countOfVisitsToATransaction
    • ga:sourceMedium
    • ga:percentNewVisits

  • The following dimensions have been renamed:

    • ga:countOfVisits is now ga:visitCount
    • ga:countOfVisitsToATransaction is now ga:visitsToTransaction

Release 2009-09 (September 18, 2009)

This release adds new features and deprecates some old functionality:

  • The following dimensions and metrics are now deprecated. We’ll be permanently removing them from our API in one month. Please make sure to update your code so your applications don’t break:

    • ga:countOfVisits
    • ga:countOfVisitsToATransaction
    • ga:sourceMedium
    • ga:percentNewVisits

  • The following Dimensions have been renamed:

    • ga:countOfVisits is now ga:visitCount
    • ga:countOfVisitsToATransaction is now ga:visitsToTransaction

  • All Event Tracking data is now exposed as 2 new groups:

    D7. Events (Dimensions)

    • ga:eventCategory
    • ga:eventAction
    • ga:eventLabel

    M7. Events (Metrics)

    • ga:eventValue
    • ga:totalEvents
    • ga:uniqueEvents

  • Overall site navigation data is is now exposed through the following dimensions:

    D6. Navigation

    • ga:previousPagePath
    • ga:nextPagePath

  • Landing page navigation is now exposed through the following dimensions:

    D3. Content

    • ga:landingPagePath
    • ga:secondPagePath

  • The maximum length of regular expressions in the Data Feed’s filter query parameter has been raised from 32 to 128 characters.

  • The Length of Visit report (found through the UI under Visitors -> Visitor Loyalty) is now exposed through the new dimension:

    • ga:visitLength

Release 2009-06 (June 30, 2009)

This release updates the Google Analytics Data Export API as follows:

  • Some restrictions on dimension and metric combinations have been relaxed. You can now query most content and visitor level dimensions together, for example ga:pagePath and ga:source is now a valid combination. Please see the updated reference guide for these new combinations: http://code.google.com/apis/analytics/docs/gdata/gdataReferenceValidCombos.html

  • The total number of rows that can be asked for in one request has been increased to 10,000. The default number of rows returned is still 1,000, but can now be increased by setting the max-results query parameter.

  • The Account Feed now returns two new data elements for each Table ID (currency and timezone).
    <dxp:property name='ga:currency' value='USD'/>
    <dxp:property name='ga:timezone' value='America/Los_Angeles'/>

  • We’re now enforcing that data queries must include at least one valid metric.

  • All previous deprecation changes have taken effect.

Release 2009-05 (May 22, 2009)

This release removes deprecated features from our private beta:

  • The account feed requests will no longer support a username in them. Instead, it will only accept requests in the following format:
    https://www.google.com/analytics/feeds/accounts/default

  • The following metrics are being removed and will no longer work. Instead, we have provided instructions on how to calculate these values here: http://code.google.com/apis/analytics/docs/gdata/gdataReferenceCommonCalculations.html

    • ga:avgPageDuration
    • ga:avgPageviews
    • ga:avgSessionTime
    • ga:bounceRate
    • ga:exitRate
    • ga:costPerConversion
    • ga:costPerGoalConversion
    • ga:costPerTransaction
    • ga:revenuePerClick
    • ga:revenuePerTransaction
    • ga:revenuePerVisit
    • ga:abandonedFunnels1
    • ga:abandonedFunnels2
    • ga:abandonedFunnels3
    • ga:abandonedFunnels4
    • ga:goalConversionRate
    • ga:goalConversionRate1
    • ga:goalConversionRate2
    • ga:goalConversionRate3
    • ga:goalConversionRate4
    • ga:goalValuePerVisit

  • The following dimensions and metrics have been renamed. The old names will no longer work. Please verify you are using the official names in our documentation here: http://code.google.com/apis/analytics/docs/gdata/gdataReferenceDimensionsMetrics.html

    Dimensions

    • ga:subContinentRegion ⇒ ga:subContinent
    • ga:organization ⇒ ga:networkLocation
    • ga:domain ⇒ ga:networkDomain
    • ga:visitNumber ⇒ ga:countOfVisits
    • ga:platform ⇒ ga:operatingSystem
    • ga:platformVersion ⇒ ga:operatingSystemVersion
    • ga:content ⇒ ga:adContent
    • ga:requestUri ⇒ ga:pagePath
    • ga:requestUri1 ⇒ ga:landingPagePath
    • ga:requestUriLast ⇒ ga:exitPagePath
    • ga:internalSearchNext ⇒ ga:searchKeywordRefinement
    • ga:internalSearchKeyword ⇒ ga:searchKeyword
    • ga:internalSearchType ⇒ ga:searchCategory
    • ga:hasInternalSearch ⇒ ga:searchUsed
    • ga:requestUriFrom ⇒ ga:searchStartPage
    • ga:requestUriTo ⇒ ga:searchDestinationPage
    • ga:productCode ⇒ ga:productSku

    Metrics

    • ga:newVisitors ⇒ ga:newVisits
    • ga:pageDuration ⇒ ga:timeOnPage
    • ga:visitDuration ⇒ ga:timeOnSite
    • ga:cost ⇒ ga:adCost
    • ga:clicks ⇒ ga:adClicks
    • ga:clickThroughRate ⇒ ga:CTR
    • ga:costPerClick ⇒ ga:CPC
    • ga:costPerMilleImpressions ⇒ ga:CPM
    • ga:searchTransitions ⇒ ga:searchRefinements
    • ga:uniqueInternalSearches ⇒ ga:searchUniques
    • ga:visitsWithSearches ⇒ ga:searchVisits
    • ga:productPurchases ⇒ ga:itemQuantity
    • ga:productRevenue ⇒ ga:itemRevenue
    • ga:products ⇒ ga:uniquePurchases
    • ga:revenue ⇒ ga:transactionRevenue
    • ga:shipping ⇒ ga:transactionShipping
    • ga:tax ⇒ ga:transactionTax
    • ga:goalCompletions1 ⇒ ga:goal1Completions
    • ga:goalCompletions2 ⇒ ga:goal2Completions
    • ga:goalCompletions3 ⇒ ga:goal3Completions
    • ga:goalCompletions4 ⇒ ga:goal4Completions
    • ga:goalStarts1 ⇒ ga:goal1Starts
    • ga:goalStarts2 ⇒ ga:goal2Starts
    • ga:goalStarts3 ⇒ ga:goal3Starts
    • ga:goalStarts4 ⇒ ga:goal4Starts
    • ga:goalValue1 ⇒ ga:goal1Value
    • ga:goalValue2 ⇒ ga:goal2Value
    • ga:goalValue3 ⇒ ga:goal3Value
    • ga:goalValue4 ⇒ ga:goal4Value

Back to top