Changelog

For official Google Analytics API announcements, please subscribe to Google Analytics API Notify Group.

2023-09-12 AudienceList default ordering rules

By default, reports created using the Audience Lists export functionality follow the same ordering rules as the other reporting methods of the Data API: the ordering will be descending by first column, then descending by second column, etc.

Before this change, you might have received the following report:

deviceId isAdsPersonalizationAllowed
ABC true
DAC false
ABC false
AAA true

After this change, you will receive the following report:

deviceId isAdsPersonalizationAllowed
AAA true
ABC false
ABC true
DAC false

2023-08-15 Added isLimitedAdTracking dimension to the Audience List export schema

  • isLimitedAdTracking The device's Limit Ad Tracking setting. Possible values include: true, false, and (not set).

    To learn more, see Audience List Dimensions.

2023-08-15 Added currencyCode dimension, itemDiscountAmount metric

  • currencyCode The local currency code (based on ISO 4217 standard) of the eCommerce event. For example, 'USD' or 'GBP'.

  • itemDiscountAmount The monetary value of item discounts in eCommerce events. This metric is populated in tagging by the 'discount' item parameter.

To learn more, see Data API reporting schema.

2023-08-10 Added isAdsPersonalizationAllowed dimension to the Audience List export schema

  • isAdsPersonalizationAllowed Is ads personalization allowed. If a user is eligible for ads personalization isAdsPersonalizationAllowed returns true. If a user is not eligible for ads personalization, isAdsPersonalizationAllowed returns false.

    To learn more, see Audience List Dimensions.

2023-07-10 Audience Lists

Audience Lists support added to the Data API v1 alpha. Audiences Lists include a snapshot of the users in the audience at the time of Audience List creation.

The following methods added to the Data API v1 alpha:

2023-05-19 Custom Channel Groups

Custom channel groups support added to the Data API.

2023-05-11 Tokens quota changes.

The quota system of the Data API has been updated to allow for more precise charges.

The number of tokens charged for each request has been updated in line with the quota change and rebalanced in a way to allow for a larger number of simple reporting queries, while charging significantly more quota tokens for large date reports.

After this change, while the charge for some requests will remain the same, there will be a noticeable increase in the charges for more complicated queries. For example, requests for more than 6 months of data can charge 1,000 or more quota tokens.

Standard Properties

Quota Name Old Limit New Limit
Core Tokens Per Property Per Day 25,000 200,000
Core Tokens Per Property Per Hour 5,000 40,000
Core Tokens Per Project Per Property Per Hour 1,750 14,000
Realtime Tokens Per Property Per Day 25,000 200,000
Realtime Tokens Per Property Per Hour 5,000 40,000
Realtime Tokens Per Project Per Property Per Hour 1,750 14,000
Funnel Tokens Per Property Per Day 25,000 200,000
Funnel Tokens Per Property Per Hour 5,000 40,000
Funnel Tokens Per Project Per Property Per Hour 1,750 14,000

Analytics 360 Properties

Quota Name Old Limit New Limit
Core Tokens Per Property Per Day 250,000 2,000,000
Core Tokens Per Property Per Hour 50,000 400,000
Core Tokens Per Project Per Property Per Hour 17,500 140,000
Realtime Tokens Per Property Per Day 250,000 2,000,000
Realtime Tokens Per Property Per Hour 50,000 400,000
Realtime Tokens Per Project Per Property Per Hour 17,500 140,000
Funnel Tokens Per Property Per Day 250,000 2,000,000
Funnel Tokens Per Property Per Hour 50,000 400,000
Funnel Tokens Per Project Per Property Per Hour 17,500 140,000

2023-03-02 Added date dimensions.

  • dayOfWeekName Day of week name. The day of the week in English. This dimension has values of Sunday, Monday, etc.

  • isoWeek ISO week of the year. ISO week number, where each week starts on Monday. For details, see https://en.wikipedia.org/wiki/ISO_week_date. Example values include 01, 02, & 53.

  • isoYear ISO year. The ISO year of the event. For details, see https://en.wikipedia.org/wiki/ISO_week_date. Example values include 2022 & 2023.

  • isoYearIsoWeek ISO week of ISO year. The combined values of isoWeek and isoYear. Example values include 201652 & 201701.

  • yearMonth Year month. The combined values of year and month. Example values include 202212 or 202301.

  • yearWeek Year week. The combined values of year and week. Example values include 202253 or 202301.

2023-02-27 Added e-commerce dimensions.

  • itemListPosition Item list position. The position of an item (e.g., a product you sell) in a list. This dimension is populated in tagging by the 'index' parameter in the items array.

  • itemLocationID Item location ID. The physical location associated with the item (e.g. the physical store location). It's recommended to use the Google Place ID that corresponds to the associated item. A custom location ID can also be used. This field is populated in tagging by the 'location_id' parameter in the items array.

  • itemPromotionCreativeSlot Item promotion creative slot. The name of the promotional creative slot associated with the item. This dimension can be specified in tagging by the creative_slot parameter at the event or item level. If the parameter is specified at both the event & item level, the item-level parameter is used.

2023-02-21 Added 'Landing page + query string' dimension.

  • landingPagePlusQueryString Landing page + query string. The page path + query string associated with the first pageview in a session.

This field replaces the landingPage dimension which is deprecated and will be updated to not return a query string on May 14, 2023.

2023-01-28 Added 'Views per user', 'Scrolled users' metrics.

  • screenPageViewsPerUser Views per user. The number of app screens or web pages your users viewed per active user. Repeated views of a single page or screen are counted. (screen_view + page_view events) / active users.

  • scrolledUsers Scrolled users. The number of unique users who scrolled down at least 90% of the page.

2023-01-23 Added 'Continent', 'Continent ID' dimensions.

  • continent Continent. The continent from which the user activity originated. For example, Americas or Asia.

  • continentId Continent ID. The geographic ID of the continent from which the user activity originated, derived from their IP address.

2023-01-23 Added 'Test data filter ID' dimension.

  • testDataFilterId Test data filter ID. The numeric identifier of a data filter in testing state. You use data filters to include or exclude event data from your reports based on event-parameter values. To learn more, see https://support.google.com/analytics/answer/10108813.

2022-10-18 Added Ads metrics.

  • advertiserAdClicks Ads clicks. Total number of times users have clicked on an ad to reach the property.
  • advertiserAdCost Ads cost. The total amount you paid for your ads.
  • advertiserAdCostPerClick Ads cost per click. Ads cost per click is ad cost divided by ad clicks and is often abbreviated CPC.
  • advertiserAdCostPerConversion Cost per conversion. Cost per conversion is ad cost divided by conversions.
  • advertiserAdImpressions Ads impressions. The total number of impressions.
  • returnOnAdSpend Return on ad spend. Return On Ad Spend (ROAS) is total revenue divided by advertiser ad cost.

2022-10-17 Added item-scoped metrics.

  • itemsAddedToCart Items added to cart. The number of units added to cart for a single item.
  • itemsCheckedOut Items checked out. The number of units checked out for a single item.
  • itemsClickedInList Items clicked in list. The number of units clicked in list for a single item.
  • itemsClickedInPromotion Items clicked in promotion. The number of units clicked in promotion for a single item.
  • itemsViewed Items viewed. The number of units viewed for a single item.
  • itemsViewedInList Items viewed in list. The number of units viewed in list for a single item.
  • itemsViewedInPromotion Items viewed in promotion. The number of units viewed in promotion for a single item.

2022-09-13 Schema compatibility changes announcement.

On December 1st 2022, the following breaking changes will occur:

  1. Item-scoped dimensions like itemName are becoming incompatible with event-scoped metrics like eventCount. Item-scoped dimensions will still be compatible with item-scoped metrics like itemRevenue, user-based metrics like activeUsers, and session-based metrics like sessions.

  2. Attribution dimensions like source are becoming incompatible with some event-scoped metrics like eventCount. Attribution dimensions will still be compatible with attributable metrics like conversions, user-based metrics like activeUsers, and session-based metrics like sessions.

  3. Dimensions that include the query string like pagePathPlusQueryString will only be compatible with a limited set of dimensions & metrics.

To learn more, see the detailed explanation of compatibility changes.

2022-09-01 Quota changes.

  • Requests per day , Requests Per Minute, Requests Per Minute Per User quotas are removed from the Data API.

  • Tokens Per Project Per Property Per Hour quota has been added to the API.

  • Each request consumes quota for both Tokens Per Property Per Hour and Tokens Per Project Per Property Per Hour.

    See the Quotas documentation for the detailed information on new quotas.

2022-08-03 Added session scoped SA360 dimensions.

  • sessionSa360AdGroupName Session SA360 ad group name. The Ad Group name from Search Ads 360 that led to this session.

  • sessionSa360CampaignName Session SA360 campaign. The Campaign name from Search Ads 360 that led to this session.

  • sessionSa360CreativeFormat Session SA360 creative format. The type of creative in Search Ads 360 that led to this session. For example, 'Responsive search ad' or 'Expanded text ad'.

  • sessionSa360EngineAccountId Session SA360 engine account ID. The ID of the engine account in SA360 that led to this session.

  • sessionSa360EngineAccountName Session SA360 engine account name. The name of the engine account in SA360 that led to this session.

  • sessionSa360EngineAccountType Session SA360 engine account type. The type of the engine account in Search Ads 360 that led to this session. For example, 'google ads', 'bing', or 'baidu'.

  • sessionSa360Keyword Session SA360 keyword text. The search engine keyword from Search Ads 360 that led to this session.

  • sessionSa360Medium Session SA360 medium. The search engine keyword from Search Ads 360 that led to this session. For example, 'cpc'.

  • sessionSa360Query Session SA360 query. The search query from Search Ads 360 that led to this session.

  • sessionSa360Source Session SA360 source. The source of the traffic from Search Ads 360 that led to this session. For example, 'example.com' or 'google'.

  • sessionCampaignId, sessionCampaignName dimensions now support Search Ads 360 campaigns.

2022-07-11 Added conversion rate metrics.

Conversion rate

  • sessionConversionRate The percentage of sessions in which any conversion event was triggered.

  • userConversionRate The percentage of users who triggered any conversion event.

Conversion Rate Metrics For One Conversion

  • sessionConversionRate:event_name The percentage of sessions in which a specific conversion event was triggered.

  • userConversionRate:event_name The percentage of users who triggered a specific conversion event.

2022-05-05 Added Funnel reporting functionality to the Alpha channel.

  • runFunnelReport method added to the v1alpha version of the API, which returns a customized funnel report of your Google Analytics event data.

  • This method is introduced at alpha stability with the intention of gathering feedback on syntax and capabilities before entering beta. Please complete the Google Analytics Data API Funnel Reporting Feedback to give your feedback on this API.

2022-02-16 Added new dimensions.

Manual term & content

  • firstUserManualAdContent First user manual ad content. The ad content that first acquired the user. Populated by the utm_content parameter.

  • firstUserManualTerm First user manual term. The term that first acquired the user. Populated by the utm_term parameter.

  • manualAdContent Manual ad content. The ad content attributed to the conversion event. Populated by the utm_content parameter.

  • manualTerm Manual term. The term attributed to the conversion event. Populated by the utm_term parameter.

  • sessionManualAdContent Session manual ad content. The ad content that led to a session. Populated by the utm_content parameter.

  • sessionManualTerm Session manual term. The term that led to a session. Populated by the utm_term parameter.

Crash analysis

  • crashAffectedUsers Crash-affected users. The number of users that logged a crash in this row of the report.

  • crashFreeUsersRate Crash-free users rate.

App/Web

  • averageSessionDuration The average duration (in seconds) of users' sessions.

  • newVsReturning New / returning users.

  • screenPageViewsPerSession Views per session.

  • landingPage Landing page. The page path + query string associated with the first pageview in a session.

  • platformDeviceCategory The platform and type of device on which your website or mobile app ran.

Mobile App

  • averagePurchaseRevenuePerUser Average purchase revenue per user.

  • firstTimePurchaserConversionRate The percentage of active users who made their first purchase.

  • firstTimePurchasersPerNewUser The average number of first time purchasers per new user.

  • dauPerMau DAU / MAU. The rolling percent of 30-day active users who are also 1-day active users.

  • dauPerWau DAU / WAU. The rolling percent of 7-day active users who are also 1-day active users.

  • wauPerMau WAU / MAU. The rolling percent of 30-day active users who are also 7-day active users.

  • purchaserConversionRate The percentage of active users who made 1 or more purchase transactions.

  • transactionsPerPurchaser Transactions per purchaser.

Google Ads campaign

  • firstUserGoogleAdsCampaignType The campaign type of the Google Ads campaign that first acquired the user.

  • googleAdsCampaignType The campaign type for the Google Ads campaign attributed to the conversion event.

  • sessionGoogleAdsCampaignType The campaign type for the Google Ads campaign that led to this session.

2021-09-07 Added new Date/time dimensions.

  • dateHourMinute The combined values of date, hour, and minute formatted as YYYYMMDDHHMM.

  • minute The two-digit minute of the hour that the event was logged.

  • nthMinute The number of minutes since the start of the date range.

2021-09-07 Added new dimensions populated by event parameters.

  • achievementId The achievement ID in a game for an event.

  • character The player character in a game for an event.

  • fileExtension The extension of the downloaded file.

  • fileName The page path of the downloaded file.

  • groupId The player group ID in a game for an event.

  • linkClasses The HTML class attribute for an outbound link.

  • linkDomain The destination domain of the outbound link.

  • linkId The HTML id attribute for an outbound link or file download.

  • linkText The link text of the file download.

  • linkUrl The full url for an outbound link or file download.

  • method The method by which an event was triggered.

  • outbound Returns 'true' if the link leads to a site is not a part of the property’s domain.

  • pageLocation The protocol, hostname, page path, and query string for web pages visited.

  • pageReferrer The full referring URL including the hostname and path.

  • percentScrolled The percentage down the page that the user has scrolled (for example, '90').

  • searchTerm The term searched by the user.

  • videoProvider The source of the video (for example, 'youtube').

  • videoTitle The title of the video.

  • videoUrl The url of the video.

  • visible Returns 'true' if the content is visible.

  • unifiedPagePathScreen The page path (web) or screen class (app) on which the event was logged.

2021-09-07 API schema changes.

Changes in existing dimensions:

  • unifiedPageScreen For web generated events, this dimension now returns the page path and query string on which the event was logged.

Upcoming changes announcement:

  • firstUserTrafficOrigin The traffic origin that first acquired the user. Please do not depend on this field returning 'Manual' for traffic that uses UTMs; this field will update from returning 'Manual' to returning '(not set)' for an upcoming feature launch.

  • sessionTrafficOrigin The traffic origin of the session's campaign. Please do not depend on this field returning 'Manual' for traffic that uses UTMs; this field will update from returning 'Manual' to returning '(not set)' for an upcoming feature launch.

  • trafficOrigin The traffic origin of the conversion event's campaign. Please do not depend on this field returning 'Manual' for traffic that uses UTMs; this field will update from returning 'Manual' to returning '(not set)' for an upcoming feature launch.

2021-09-07 checkCompatibility method added to the API.

checkCompatibility method lists dimensions and metrics that can be added to a report request and maintain compatibility.

2021-07-21 Realtime reporting changes.

It is now possible to specify the minute ranges of event data to read using the minuteRanges parameter of the runRealtimeReport method.

2021-07-21 New channel grouping dimensions.

New channel grouping dimensions added to the Data API reporting schema:

  • firstUserDefaultChannelGrouping First user default channel grouping.

  • defaultChannelGrouping Default channel grouping.

2021-06-10 API schema changes.

  • minutesAgo dimension added to the Data API realtime schema and can be used in queries to the runRealtimeReport method. This dimension contains the number of minutes ago that an event was collected. 00 is the current minute, and 01 means the previous minute.

  • googleAdsCreativeId dimension added to the Data API schema. This dimension contains the ID of the Google Ads creative attributed to the conversion event.

  • sessionGoogleAdsCreativeId dimension added to the Data API schema. This dimension contains the ID of the Google Ads creative that lead to a session on your website or app.

  • firstUserCreativeId dimension renamed to firstUserGoogleAdsCreativeId in the Data API schema. This dimension contains the ID of the Google Ads creative that first acquired the user.

2021-04-09 The Google Analytics Data API v1 beta has been released.

  • The API endpoint updated to https://analyticsdata.googleapis.com/v1beta.

  • runReport, runPivotReport, batchRunReports, batchRunPivotReports methods now accept the id of a Google Analytics 4 property in the property parameter of the URL path instead of the entity field of a request body:

    POST https://analyticsdata.googleapis.com/v1beta/GA4_PROPERTY_ID:batchRunReports

  • API client libraries have been updated to use the new API endpoint.

2021-02-19 Pagination changes.

  • The default report response size increased from 10 to 10,000 rows of event data.

  • "limit" : -1 value that was used to indicate an attempt to retrieve all rows is no longer supported in RunReportRequest.

  • The maximum value of the limit field is set to 100000. Use pagination to retrieve reports containing more than 100,000 rows.

2021-02-08 New e-commerce dimensions and metrics.

New e-commerce dimensions and metrics have been added to the API schema:

Dimensions: adFormat, adSourceName, adUnitName, itemBrand, itemCategory, itemCategory2, itemCategory3, itemCategory4, itemCategory5 itemId, itemListId, itemListName, itemName, itemPromotionCreativeName, itemPromotionId, itemPromotionName, orderCoupon, transactionId.

Metrics: adUnitExposure, addToCarts, cartToViewRate, checkouts, ecommercePurchases, firstTimePurchasers, itemListClickThroughRate, itemListClicks, itemListViews, itemPromotionClickThroughRate, itemPromotionClicks, itemPromotionViews, itemPurchaseQuantity, itemRevenue, itemViews, publisherAdClicks, publisherAdImpressions, totalPurchasers.

2021-02-08 Added new campaign dimensions.

New campaign dimensions have been added to the API schema: campaignId, campaignName, googleAdsAccountName, googleAdsAdGroupId, googleAdsAdGroupName, googleAdsAdNetworkType, source, trafficOrigin

2021-02-08 dayOfWeek, week dimension changes.

  • The value of dayOfWeek dimension now starts with 0 instead of 1.

  • The value of week dimension now starts with 01 and returns a two-digit number from 01 to 53. Each week starts on Sunday. January 1st is always in week 01.

2021-01-28 Added aggregation variants for custom metrics.

Each custom metric that a property registers creates three API metric variants: a sum, an average, and a count.

2021-01-28 Added new Date/time dimensions.

The following new dimensions have been added to the API schema: hour, nthHour, nthYear, dateHour.

2021-01-28 The Data API reduced the quota tokens charged per query.

The Data API reduced the quota tokens charged per query. The quota limits for property quota tokens per hour and per day were not changed.

2020-11-09 The method getUniversalMetadata has been deleted.

The method getUniversalMetadata has been deleted. Please use getMetadata. The one year maximum date range per API request has been removed.

2020-11-02 Added a Realtime Reporting Method.

See the Creating a Realtime Report for examples and runRealtimeReport for the REST reference documentation.

2020-10-19 Client library artifacts updated.

Client library artifacts updated along with usage instructions and code samples.

2020-10-13 App + Web properties have been renamed to Google Analytics 4 (GA4).

2020-10-08 getMetadata method added to the API.

getMetadata method returns Custom dimensions and metrics available for the specified GA4 property ID, as well as Universal metadata.

2020-10-08 Custom dimensions and metrics are available in reports.

See the API schema documentation for documentation on custom dimensions and metrics. This update includes Event-scoped Custom Dimensions and metrics as well as User-scoped Custom Dimensions.