API Dimensions & Metrics

The dimensions and metrics supported in the Analytics Data API queries.

Dimensions

The following dimensions can be requested in reports for any property. Specify the "API Name" in a Dimension's name field for a column of the dimension in the report response.

API Name UI Name Description
adFormat Ad format Describes the way ads looked and where they were located. Typical formats include 'Interstitial', 'Banner', 'Rewarded', and 'Native advanced'.
adSourceName Ad source The source network that served the ad. Typical sources include 'AdMob Network', 'Liftoff', 'Facebook Audience Network', and 'Mediated house ads'.
adUnitName Ad unit The name you chose to describe this Ad unit. Ad units are containers you place in your apps to show ads to users.
appVersion App version The app's versionName (Android) or short bundle version (iOS).
audienceId Audience ID The numeric identifier of an Audience. Users are reported in the audiences to which they belonged during the report's date range. Current user behavior does not affect historical audience membership in reports.
audienceName Audience name The given name of an Audience. Users are reported in the audiences to which they belonged during the report's date range. Current user behavior does not affect historical audience membership in reports.
brandingInterest Interests Interests demonstrated by users who are higher in the shopping funnel. Users can be counted in multiple interest categories. For example, 'Shoppers', 'Lifestyles & Hobbies/Pet Lovers', or 'Travel/Travel Buffs/Beachbound Travelers'.
browser Browser The browsers used to view your website.
campaignId Campaign ID The identifier of the marketing campaign. Present only for conversion events.
campaignName Campaign The name of the marketing campaign. Present only for conversion events.
city City The city from which the user activity originated.
cityId City ID The geographic ID of the city from which the user activity originated, derived from their IP address.
cohort Cohort The cohort's name in the request. A cohort is a set of users who started using your website or app in any consecutive group of days. If a cohort name is not specified in the request, cohorts are named by their zero based index: cohort_0, cohort_1, etc.
cohortNthDay Daily cohort Day offset relative to the firstTouchDate for the users in the cohort. For example, if a cohort is selected with the start and end date of 2020-03-01, then for the date 2020-03-02, cohortNthDay will be 0001.
cohortNthMonth Monthly cohort Month offset relative to the firstTouchDate for the users in the cohort. Month boundaries align with calendar month boundaries. For example, if a cohort is selected with the start and end date in March 2020, then for any date in April 2020, cohortNthMonth will be 0001.
cohortNthWeek Weekly cohort Week offset relative to the firstTouchDate for the users in the cohort. Weeks start on Sunday and end on Saturday. For example, if a cohort is selected with the start and end date in the range 2020-11-08 to 2020-11-14, then for the dates in the range 2020-11-15 to 2020-11-21, cohortNthWeek will be 0001.
contentGroup Content group A category that applies to items of published content.
contentId Content ID The identifier of the selected content.
contentType Content type The category of the selected content.
country Country The country from which the user activity originated.
countryId Country ID The geographic ID of the country from which the user activity originated, derived from their IP address. Formatted according to ISO 3166-1 alpha-2 standard.
date Date The date of the event, formatted as YYYYMMDD.
dateHour Date + hour (YYYYMMDDHH) The combined values of date and hour formatted as YYYYMMDDHH.
day Day The day of the month, a two-digit number from 01 to 31.
dayOfWeek Day of week The day of the week. It returns values in the range [0,6] with Sunday as the first day of the week.
deviceCategory Device category The type of device: Desktop, Tablet, or Mobile.
deviceModel Device model The mobile device model (example: iPhone 10,6).
eventName Event name The name of the event.
firstSessionDate First session date The date the user's first session occurred, formatted as YYYYMMDD.
firstUserCampaignId User acquired campaign ID Identifier of the marketing campaign that first acquired the user. Includes Google Ads Campaigns.
firstUserCampaignName User campaign Name of the marketing campaign that first acquired the user. Includes Google Ads and Manual Campaigns.
firstUserCreativeId User campaign creative ID The campaign creative ID that first acquired the user.
firstUserGoogleAdsAdGroupId User Google Ads ad group ID The Ad Group Id in Google Ads that first acquired the user.
firstUserGoogleAdsAdGroupName User Google Ads ad group name The Ad Group Name in Google Ads that first acquired the user.
firstUserGoogleAdsAdNetworkType User Google Ads ad network type The advertising network that first acquired the user. An enumeration which includes 'Google search', 'Search partners', 'Google Display Network', 'Youtube Search', 'Youtube Videos', 'Cross-network', 'Social', and '(universal campaign)'.
firstUserGoogleAdsKeyword User Google Ads keyword text The matched keyword that first acquired the user. Keywords are words or phrases describing your product or service that you choose to get your ad in front of the right customers. To learn more about Keywords, see https://support.google.com/google-ads/answer/6323.
firstUserGoogleAdsQuery User Google Ads query The search query that first acquired the user.
firstUserMedium User medium The medium that first acquired the user to your website or app.
firstUserSource User source The source that first acquired the user to your website or app.
firstUserTrafficOrigin User acquired campaign traffic origin The traffic origin that first acquired the user. An enumeration which includes 'Google Ads', 'Manual', and '(not set)'.
fullPageUrl Full page URL The hostname, page path, and query string for web pages visited; for example, the fullPageUrl portion of https://www.example.com/store/contact-us?query_string=true is www.example.com/store/contact-us?query_string=true.
googleAdsAccountName Google Ads account name The customer's descriptive name in Google Ads for the conversion event's campaign. Corresponding to customer.descriptive_name in the Google Ads API.
googleAdsAdGroupId Google Ads ad group ID The ad group id attributed the conversion event.
googleAdsAdGroupName Google Ads ad group name The ad group name attributed the conversion event.
googleAdsAdNetworkType Google Ads ad network type The advertising network type of the conversion. An enumeration which includes 'Google search', 'Search partners', 'Google Display Network', 'Youtube Search', 'Youtube Videos', 'Cross-network', 'Social', and '(universal campaign)'.
googleAdsKeyword Event Google Ads keyword text The matched keyword that led to the conversion event. Keywords are words or phrases describing your product or service that you choose to get your ad in front of the right customers. To learn more about Keywords, see https://support.google.com/google-ads/answer/6323.
googleAdsQuery Google Ads query The search query that led to the conversion event.
hostName Hostname Includes the subdomain and domain names of a URL; for example, the Host Name of www.example.com/contact.html is www.example.com.
hour Hour The two-digit hour of the day that the event was logged. This dimension ranges from 00-23 and is reported in your property's timezone.
isConversionEvent Is conversion event The string 'true' if the event is a conversion. Events are marked as conversions at collection time; changes to an event's conversion marking apply going forward. You can mark any event as a conversion in Google Analytics, and some events (i.e. first_open, purchase) are marked as conversions by default. To learn more, see https://support.google.com/analytics/answer/9267568.
itemBrand Item brand Brand name of the item.
itemCategory Item category The hierarchical category in which the item is classified. For example, in Apparel/Mens/Summer/Shirts/T-shirts, Apparel is the item category.
itemCategory2 Item category 2 The hierarchical category in which the item is classified. For example, in Apparel/Mens/Summer/Shirts/T-shirts, Mens is the item category 2.
itemCategory3 Item category 3 The hierarchical category in which the item is classified. For example, in Apparel/Mens/Summer/Shirts/T-shirts, Summer is the item category 3.
itemCategory4 Item category 4 The hierarchical category in which the item is classified. For example, in Apparel/Mens/Summer/Shirts/T-shirts, Shirts is the item category 4.
itemCategory5 Item category 5 The hierarchical category in which the item is classified. For example, in Apparel/Mens/Summer/Shirts/T-shirts, T-shirts is the item category 5.
itemId Item ID The ID of the item.
itemListId Item list ID The ID of the item list.
itemListName Item list name The name of the item list.
itemName Item name The name of the item.
itemPromotionCreativeName Item promotion creative name The name of the item-promotion creative.
itemPromotionId Item promotion ID The ID of the item promotion.
itemPromotionName Item promotion name The name of the promotion for the item.
language Language The language setting of the user's browser or device. e.g. English
languageCode Language code The language setting (ISO 639) of the user's browser or device. e.g. 'en-us'
medium Medium The medium attributed to the conversion event.
mobileDeviceBranding Device brand Manufacturer or branded name (examples: Samsung, HTC, Verizon, T-Mobile).
mobileDeviceMarketingName Device The branded device name (examples: Galaxy S10 or P30 Pro).
mobileDeviceModel Mobile model The mobile device model name (examples: iPhone X or SM-G950F).
month Month The month of the event, a two digit integer from 01 to 12.
nthDay Nth day The number of days since the start of the date range.
nthHour Nth hour The number of hours since the start of the date range. The starting hour is 0000.
nthMonth Nth month The number of months since the start of a date range. The starting month is 0000.
nthWeek Nth week A number representing the number of weeks since the start of a date range.
nthYear Nth year The number of years since the start of the date range. The starting year is 0000.
operatingSystem Operating system The operating systems used by visitors to your app or website. Includes desktop and mobile operating systems such as Windows and Android.
operatingSystemVersion OS version The operating system versions used by visitors to your website or app. For example, Android 10's version is 10, and iOS 13.5.1's version is 13.5.1.
operatingSystemWithVersion Operating system with version The operating system and version. For example, Android 10 or Windows 7.
orderCoupon Order coupon Code for the order-level coupon.
pagePath Page path The portion of the URL between the hostname and query string for web pages visited; for example, the pagePath portion of https://www.example.com/store/contact-us?query_string=true is /store/contact-us.
pagePathPlusQueryString Page path + query string The portion of the URL following the hostname for web pages visited; for example, the pagePathPlusQueryString portion of https://www.example.com/store/contact-us?query_string=true is /store/contact-us?query_string=true.
pageTitle Page title The web page titles used on your site.
platform Platform The platform on which your app or website ran; for example, web, iOS, or Android. To determine a stream's type in a report, use both platform and streamId.
region Region The geographic region from which the user activity originated, derived from their IP address.
screenResolution Screen resolution The screen resolution of the user's monitor. For example, 1920x1080.
sessionCampaignId Last click session campaign ID The marketing campaign id for a session. Includes Google Ads Campaigns.
sessionCampaignName Session campaign The marketing campaign name for a session. Includes Google Ads and Manual Campaigns.
sessionDefaultChannelGrouping Session default channel grouping The session's default channel grouping is based primarily on source and medium. An enumeration which includes 'Direct', 'Organic Search', 'Paid Social', 'Organic Social', 'Email', 'Affiliates', 'Referral', 'Paid Search', 'Video', and 'Display'.
sessionGoogleAdsAccountName Session Google Ads account name A customer's descriptive name in Google Ads. Corresponding to customer.descriptive_name in the Google Ads API.
sessionGoogleAdsAdGroupId Session Google Ads ad group ID The Ad Group Id in Google Ads for a session.
sessionGoogleAdsAdGroupName Session Google Ads ad group name The Ad Group Name in Google Ads for a session.
sessionGoogleAdsAdNetworkType Session Google Ads ad network type The advertising network that led to the session. An enumeration which includes 'Google search', 'Search partners', 'Google Display Network', 'Youtube Search', 'Youtube Videos', 'Cross-network', 'Social', and '(universal campaign)'.
sessionGoogleAdsKeyword Session Google Ads keyword text The matched keyword that led to the session. Keywords are words or phrases describing your product or service that you choose to get your ad in front of the right customers. To learn more about Keywords, see https://support.google.com/google-ads/answer/6323.
sessionGoogleAdsQuery Session Google Ads query The search query that led to the session.
sessionMedium Session medium The medium that initiated a session on your website or app.
sessionSource Session source The source that initiated a session on your website or app.
sessionTrafficOrigin Last click session traffic origin The traffic origin of the session's campaign. An enumeration which includes 'Google Ads', 'Manual', and '(not set)'.
signedInWithUserId Signed in with user ID The string 'yes' if the user signed in with the User-ID feature. To learn more about User-ID, see https://support.google.com/analytics/answer/9213390.
source Source The source attributed to the conversion event.
streamId Stream ID The numeric data stream identifier for your app or website.
streamName Stream name The data stream name for your app or website.
testDataFilterName Test data filter name The name of data filters 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.
trafficOrigin Traffic origin The traffic origin of the conversion event's campaign. An enumeration which includes 'Google Ads', 'Manual', and '(not set)'.
transactionId Transaction ID The ID of the ecommerce transaction.
unifiedPageScreen Page path and screen class The page path (web) or screen class (app) on which the event was logged.
unifiedScreenClass Page title and screen class The page title (web) or screen class (app) on which the event was logged.
unifiedScreenName Page title and screen name The page title (web) or screen name (app) on which the event was logged.
userAgeBracket Age User age brackets.
userGender Gender User gender.
week Week The week of the event, a two-digit number from 01 to 53. Each week starts on Sunday. January 1st is always in week 01. The first and last week of the year have fewer than 7 days in most years. Weeks other than the first and the last week of the year always have 7 days. For years where January 1st is a Sunday, the first week of that year and the last week of the prior year have 7 days.
year Year The four-digit year of the event e.g. 2020.

Custom Dimensions

The Data API can create reports on Event and User scoped Custom Dimensions. See Event-scoped custom dimensions and metrics reporting and Custom user properties to learn more about custom dimensions. Custom dimensions are specified in an API report request by the dimension's parameter name and scope. For example, include "customEvent:achievement_id" in a Data API request to create a report for the Event-scoped Custom Dimension with parameter name "achievement_id". This API request will fail if the property has not registered this Event-scoped Custom Dimension.

If an Event-scoped Custom Dimension was registered before October 2020, the dimension must be specified in an API request with its event name. For example, include "customEvent:achievement_id[level_up]" for the Event-scoped Custom Dimension with parameter name "achievement_id" and event name "level_up". In October 2020, Analytics replaced Custom-parameter reporting with Event-scoped custom dimensions and metrics reporting.

The following are the general syntax for Custom Dimensions. You can query the Metadata API method to list all Custom Dimensions for a Property; here is an example of using the Metadata API method.

Generic API Name Description
customEvent:parameter_name Event-scoped Custom Dimension for parameter_name
customEvent:parameter_name[event_name] Event-scoped Custom Dimension for parameter_name if registered before October 2020
customUser:parameter_name User-scoped Custom Dimension for parameter_name

Metrics

The following metrics can be requested in reports for any property. Specify the "API Name" in a Metric's name field for a column of the metric in the report response.

API Name UI Name Description
active1DayUsers 1-day active users The number of distinct active users on your site or app within a 1 day period. The 1 day period includes the last day in the report's date range. Note: this is the same as Active Users.
active28DayUsers 28-day active users The number of distinct active users on your site or app within a 28 day period. The 28 day period includes the last day in the report's date range.
active7DayUsers 7-day active users The number of distinct active users on your site or app within a 7 day period. The 7 day period includes the last day in the report's date range.
activeUsers Active users The number of distinct users who visited your site or app.
adUnitExposure Ad unit exposure The time that an ad unit was exposed to a user, in milliseconds.
addToCarts Add-to-carts The number of times users added items to their shopping carts.
averagePurchaseRevenue Average purchase revenue The average purchase revenue in the transaction group of events.
averagePurchaseRevenuePerPayingUser ARPPU Average revenue per paying user (ARPPU) is the total purchase revenue per active user that logged a purchase event. The summary metric is for the time period selected.
averageRevenuePerUser ARPU Average revenue per active user (ARPU). The summary metric is for the time period selected. ARPU includes AdMob estimated earnings.
cartToViewRate Cart-to-view rate The number of users who added a product(s) to their cart divided by the number of users who viewed the same product(s).
checkouts Checkouts The number of times users started the checkout process.
cohortActiveUsers Cohort active users The number of users in the cohort who are active in the time window corresponding to the cohort nth day/week/month. For example for the row where cohortNthWeek = 0001, this metric is the number of users (in the cohort) who are active in week 1.
cohortTotalUsers Cohort total users The total number of users in the cohort. This metric is the same value in every row of the report for each cohort. Because cohorts are defined by a shared acquisition date, cohortTotalUsers is the same as cohortActiveUsers for the cohort's selection date range. For report rows later than the ochort's selection range, it is typical for cohortActiveUsers to be smaller than cohortTotalUsers. This difference represents users from the cohort that were not active for the later date. cohortTotalUsers is commonly used in the metric expression cohortActiveUsers/cohortTotalUsers to compute a user retention fraction for the cohort. The relationship between activeUsers and totalUsers is not equivalent to the relationship between cohortActiveUsers and cohortTotalUsers.
conversions Conversions The count of conversion events. Events are marked as conversions at collection time; changes to an event's conversion marking apply going forward. You can mark any event as a conversion in Google Analytics, and some events (i.e. first_open, purchase) are marked as conversions by default. To learn more, see https://support.google.com/analytics/answer/9267568.
ecommercePurchases Ecommerce purchases The number of times users completed a purchase. This metric counts 'purchase' events; this metric does not count 'in_app_purchase' and subscription events.
engagedSessions Engaged sessions The number of sessions that lasted longer than 10 seconds, or had a conversion event, or had 2 or more screen views.
engagementRate Engagement rate The percentage of engaged sessions (Engaged sessions divided by Sessions).
eventCount Event count The count of events.
eventCountPerUser Event count per user The average number of events per user (Event count divided by Active users).
eventValue Event value The sum of the event parameter named 'value'.
eventsPerSession Events per session The average number of events per session (Event count divided by Sessions).
firstTimePurchasers First time purchasers The number of users that completed their first purchase event.
itemListClickThroughRate Item list click through rate The number of users who selected a list(s) divided by the number of users who viewed the same list(s).
itemListClicks Item list clicks The number of times users clicked an item when it appeared in a list.
itemListViews Item list views The number of times the item list was viewed.
itemPromotionClickThroughRate Item promotion click through rate The number of users who selected a promotion(s) divided by the number of users who viewed the same promotion(s).
itemPromotionClicks Item promotion clicks The number of times an item promotion was clicked.
itemPromotionViews Item promotion views The number of times an item promotion was viewed.
itemPurchaseQuantity Item purchase quantity The number of units for a single item included in purchase events.
itemRevenue Item revenue The total revenue from items only. Item revenue is the product of its price and quantity. Item revenue excludes tax and shipping values.
itemViews Item views The number of times the item details were viewed.
newUsers New users The number of users who interacted with your site or launched your app for the first time (event triggered: first_open or first_visit).
publisherAdClicks Publisher ad clicks The number of ad_click events.
publisherAdImpressions Publisher ad impressions The number of ad_impression events.
purchaseRevenue Purchase revenue The sum of revenue from purchases made in your app or site. Purchase revenue sums the revenue for these events: purchase, ecommerce_purchase, in_app_purchase, app_store_subscription_convert, and app_store_subscription_renew.
purchaseToViewRate Purchase-to-view rate The number of users who purchased a product(s) divided by the number of users who viewed the same product(s).
screenPageViews Views The number of app screens or web pages your users viewed. Repeated views of a single page or screen are counted. (screen_view + page_view events).
sessions Sessions The number of sessions that began on your site or app (event triggered: session_start).
sessionsPerUser Sessions per user The average number of sessions per user (Sessions divided by Active Users).
totalAdRevenue Total ad revenue The total advertising revenue from both Admob and third-party sources.
totalPurchasers Total purchasers The number of users that logged purchase events for the time period selected.
totalRevenue Total revenue The sum of revenue from purchases, subscriptions, and advertising (Purchase revenue plus Subscription revenue plus Ad revenue).
totalUsers Total users The number of distinct users who have logged at least one event, regardless of whether the site or app was in use when that event was logged.
transactions Transactions The count of transaction events with purchase revenue. Transaction events are in_app_purchase, ecommerce_purchase, purchase, app_store_subscription_renew, app_store_subscription_convert, and refund.
userEngagementDuration User engagement The total amount of time (in seconds) your website or app was in the foreground of users' devices.

Custom Metrics

The Data API can create reports on Event scoped Custom Metrics. See Event-scoped custom dimensions and metrics reporting to learn more about custom metrics. Custom metrics are specified in an API report request by the metric's parameter name and scope. For example, include "customEvent:levels_unlocked" in a Data API request to create a report for the Event-scoped Custom Metric with parameter name "levels_unlocked". This API request will fail if the property has not registered this Event-scoped Custom Metric.

If an Event-scoped Custom Metric was registered before October 2020, the metric must be specified in an API request with its event name. For example, include "customEvent:levels_unlocked[tutorial_start]" for the Event-scoped Custom Metric with parameter name "levels_unlocked" and event name "tutorial_start". In October 2020, Analytics replaced Custom-parameter reporting with Event-scoped custom dimensions and metrics reporting.

The following are the general syntax for Custom Metrics. You can query the Metadata API method to list all Custom Metrics for a Property; here is an example of using the Metadata API method.

Generic API Name Description
customEvent:parameter_name Event-scoped Custom Metric for parameter_name
customEvent:parameter_name[event_name ] Event-scoped Custom Metric for parameter_name if registered before October 2020

Custom Metric Variants

Each custom metric that a property registers creates three API metric variants: a sum, an average, and a count. Most requests will use the sum of the custom metric. The average of the custom metric is useful for a summary statistic. The count of a custom metric is interesting if the number of occurrences of a parameter is useful to you.

You can query the Metadata API method to list all variants of Custom Metrics for a Property; here is an example of using the Metadata API method for a custom average.

Generic API Name Description
customEvent:parameter_name The sum of an Event-scoped Custom Metric for parameter_name
averageCustomEvent:parameter_name The average value of an Event-scoped Custom Metric for parameter_name
countCustomEvent:parameter_name The number of occurrences of an Event-scoped Custom Metric for parameter_name