- Resource: ReportTask
- ReportDefinition
- Dimension
- DimensionExpression
- CaseExpression
- ConcatenateExpression
- Metric
- DateRange
- FilterExpression
- FilterExpressionList
- Filter
- StringFilter
- MatchType
- InListFilter
- NumericFilter
- Operation
- NumericValue
- BetweenFilter
- MetricAggregation
- OrderBy
- MetricOrderBy
- DimensionOrderBy
- OrderType
- CohortSpec
- Cohort
- CohortsRange
- Granularity
- CohortReportSettings
- SamplingLevel
- ReportMetadata
- State
- Methods
Resource: ReportTask
A specific report task configuration.
JSON representation |
---|
{ "name": string, "reportDefinition": { object ( |
Fields | |
---|---|
name |
Output only. Identifier. The report task resource name assigned during creation. Format: "properties/{property}/reportTasks/{reportTask}" |
report |
Optional. A report definition to fetch report data, which describes the structure of a report. It typically includes the fields that will be included in the report and the criteria that will be used to filter the data. |
report |
Output only. The report metadata for a specific report task, which provides information about a report. It typically includes the following information: the resource name of the report, the state of the report, the timestamp the report was created, etc, |
ReportDefinition
The definition of how a report should be run.
JSON representation |
---|
{ "dimensions": [ { object ( |
Fields | |
---|---|
dimensions[] |
Optional. The dimensions requested and displayed. |
metrics[] |
Optional. The metrics requested and displayed. |
date |
Optional. Date ranges of data to read. If multiple date ranges are requested, each response row will contain a zero based date range index. If two date ranges overlap, the event data for the overlapping days is included in the response rows for both date ranges. In a cohort request, this |
dimension |
Optional. Dimension filters let you ask for only specific dimension values in the report. To learn more, see Fundamentals of Dimension Filters for examples. Metrics cannot be used in this filter. |
metric |
Optional. The filter clause of metrics. Applied after aggregating the report's rows, similar to SQL having-clause. Dimensions cannot be used in this filter. |
offset |
Optional. The row count of the start row from Google Analytics Storage. The first row is counted as row 0. When creating a report task, the |
limit |
Optional. The number of rows to return in the Report. If unspecified, 10,000 rows are returned. The API returns a maximum of 250,000 rows per request, no matter how many you ask for. The API can also return fewer rows than the requested |
metric |
Optional. Aggregation of metrics. Aggregated metric values will be shown in rows where the dimensionValues are set to "RESERVED_(MetricAggregation)". |
order |
Optional. Specifies how rows are ordered in the response. |
currency |
Optional. A currency code in ISO4217 format, such as "AED", "USD", "JPY". If the field is empty, the report uses the property's default currency. |
cohort |
Optional. Cohort group associated with this request. If there is a cohort group in the request the 'cohort' dimension must be present. |
keep |
Optional. If false or unspecified, each row with all metrics equal to 0 will not be returned. If true, these rows will be returned if they are not separately removed by a filter. Regardless of this For example if a property never logs a |
sampling |
Optional. The report's sampling level. |
Dimension
Dimensions are attributes of your data. For example, the dimension city indicates the city from which an event originates. Dimension values in report responses are strings; for example, the city could be "Paris" or "New York".
JSON representation |
---|
{
"name": string,
"dimensionExpression": {
object ( |
Fields | |
---|---|
name |
The name of the dimension. See the API Dimensions for the list of dimension names supported by core reporting methods such as If Dimensions are referenced by |
dimension |
One dimension can be the result of an expression of multiple dimensions. For example, dimension "country, city": concatenate(country, ", ", city). |
DimensionExpression
Used to express a dimension which is the result of a formula of multiple dimensions. Example usages: 1) lowerCase(dimension) 2) concatenate(dimension1, symbol, dimension2).
JSON representation |
---|
{ // Union field |
Fields | |
---|---|
Union field one_expression . Specify one type of dimension expression for DimensionExpression . one_expression can be only one of the following: |
|
lower |
Used to convert a dimension value to lower case. |
upper |
Used to convert a dimension value to upper case. |
concatenate |
Used to combine dimension values to a single dimension. For example, dimension "country, city": concatenate(country, ", ", city). |
CaseExpression
Used to convert a dimension value to a single case.
JSON representation |
---|
{ "dimensionName": string } |
Fields | |
---|---|
dimension |
Name of a dimension. The name must refer back to a name in dimensions field of the request. |
ConcatenateExpression
Used to combine dimension values to a single dimension.
JSON representation |
---|
{ "dimensionNames": [ string ], "delimiter": string } |
Fields | |
---|---|
dimension |
Names of dimensions. The names must refer back to names in the dimensions field of the request. |
delimiter |
The delimiter placed between dimension names. Delimiters are often single characters such as "|" or "," but can be longer strings. If a dimension value contains the delimiter, both will be present in response with no distinction. For example if dimension 1 value = "US,FR", dimension 2 value = "JP", and delimiter = ",", then the response will contain "US,FR,JP". |
Metric
The quantitative measurements of a report. For example, the metric eventCount
is the total number of events. Requests are allowed up to 10 metrics.
JSON representation |
---|
{ "name": string, "expression": string, "invisible": boolean } |
Fields | |
---|---|
name |
The name of the metric. See the API Metrics for the list of metric names supported by core reporting methods such as If Metrics are referenced by |
expression |
A mathematical expression for derived metrics. For example, the metric Event count per user is |
invisible |
Indicates if a metric is invisible in the report response. If a metric is invisible, the metric will not produce a column in the response, but can be used in |
DateRange
A contiguous set of days: startDate
, startDate + 1
, ..., endDate
. Requests are allowed up to 4 date ranges.
JSON representation |
---|
{ "startDate": string, "endDate": string, "name": string } |
Fields | |
---|---|
start |
The inclusive start date for the query in the format |
end |
The inclusive end date for the query in the format |
name |
Assigns a name to this date range. The dimension |
FilterExpression
To express dimension or metric filters. The fields in the same FilterExpression need to be either all dimensions or all metrics.
JSON representation |
---|
{ // Union field |
Fields | |
---|---|
Union field expr . Specify one type of filter expression for FilterExpression . expr can be only one of the following: |
|
and |
The FilterExpressions in andGroup have an AND relationship. |
or |
The FilterExpressions in orGroup have an OR relationship. |
not |
The FilterExpression is NOT of notExpression. |
filter |
A primitive filter. In the same FilterExpression, all of the filter's field names need to be either all dimensions or all metrics. |
FilterExpressionList
A list of filter expressions.
JSON representation |
---|
{
"expressions": [
{
object ( |
Fields | |
---|---|
expressions[] |
A list of filter expressions. |
Filter
An expression to filter dimension or metric values.
JSON representation |
---|
{ "fieldName": string, // Union field |
Fields | |
---|---|
field |
The dimension name or metric name. Must be a name defined in dimensions or metrics. |
Union field one_filter . Specify one type of filter for Filter . one_filter can be only one of the following: |
|
string |
Strings related filter. |
in |
A filter for in list values. |
numeric |
A filter for numeric or date values. |
between |
A filter for between two values. |
StringFilter
The filter for string
JSON representation |
---|
{
"matchType": enum ( |
Fields | |
---|---|
match |
The match type for this filter. |
value |
The string value used for the matching. |
case |
If true, the string value is case sensitive. |
MatchType
The match type of a string filter
Enums | |
---|---|
MATCH_TYPE_UNSPECIFIED |
Unspecified |
EXACT |
Exact match of the string value. |
BEGINS_WITH |
Begins with the string value. |
ENDS_WITH |
Ends with the string value. |
CONTAINS |
Contains the string value. |
FULL_REGEXP |
Full match for the regular expression with the string value. |
PARTIAL_REGEXP |
Partial match for the regular expression with the string value. |
InListFilter
The result needs to be in a list of string values.
JSON representation |
---|
{ "values": [ string ], "caseSensitive": boolean } |
Fields | |
---|---|
values[] |
The list of string values. Must be non-empty. |
case |
If true, the string value is case sensitive. |
NumericFilter
Filters for numeric or date values.
JSON representation |
---|
{ "operation": enum ( |
Fields | |
---|---|
operation |
The operation type for this filter. |
value |
A numeric value or a date value. |
Operation
The operation applied to a numeric filter
Enums | |
---|---|
OPERATION_UNSPECIFIED |
Unspecified. |
EQUAL |
Equal |
LESS_THAN |
Less than |
LESS_THAN_OR_EQUAL |
Less than or equal |
GREATER_THAN |
Greater than |
GREATER_THAN_OR_EQUAL |
Greater than or equal |
NumericValue
To represent a number.
JSON representation |
---|
{ // Union field |
Fields | |
---|---|
Union field one_value . One of a numeric value one_value can be only one of the following: |
|
int64 |
Integer value |
double |
Double value |
BetweenFilter
To express that the result needs to be between two numbers (inclusive).
JSON representation |
---|
{ "fromValue": { object ( |
Fields | |
---|---|
from |
Begins with this number. |
to |
Ends with this number. |
MetricAggregation
Represents aggregation of metrics.
Enums | |
---|---|
METRIC_AGGREGATION_UNSPECIFIED |
Unspecified operator. |
TOTAL |
SUM operator. |
MINIMUM |
Minimum operator. |
MAXIMUM |
Maximum operator. |
COUNT |
Count operator. |
OrderBy
Order bys define how rows will be sorted in the response. For example, ordering rows by descending event count is one ordering, and ordering rows by the event name string is a different ordering.
JSON representation |
---|
{ "desc": boolean, // Union field |
Fields | |
---|---|
desc |
If true, sorts by descending order. |
Union field one_order_by . Specify one type of order by for OrderBy . one_order_by can be only one of the following: |
|
metric |
Sorts results by a metric's values. |
dimension |
Sorts results by a dimension's values. |
MetricOrderBy
Sorts by metric values.
JSON representation |
---|
{ "metricName": string } |
Fields | |
---|---|
metric |
A metric name in the request to order by. |
DimensionOrderBy
Sorts by dimension values.
JSON representation |
---|
{
"dimensionName": string,
"orderType": enum ( |
Fields | |
---|---|
dimension |
A dimension name in the request to order by. |
order |
Controls the rule for dimension value ordering. |
OrderType
Rule to order the string dimension values by.
Enums | |
---|---|
ORDER_TYPE_UNSPECIFIED |
Unspecified. |
ALPHANUMERIC |
Alphanumeric sort by Unicode code point. For example, "2" < "A" < "X" < "b" < "z". |
CASE_INSENSITIVE_ALPHANUMERIC |
Case insensitive alphanumeric sort by lower case Unicode code point. For example, "2" < "A" < "b" < "X" < "z". |
NUMERIC |
Dimension values are converted to numbers before sorting. For example in NUMERIC sort, "25" < "100", and in ALPHANUMERIC sort, "100" < "25". Non-numeric dimension values all have equal ordering value below all numeric values. |
CohortSpec
The specification of cohorts for a cohort report.
Cohort reports create a time series of user retention for the cohort. For example, you could select the cohort of users that were acquired in the first week of September and follow that cohort for the next six weeks. Selecting the users acquired in the first week of September cohort is specified in the cohort
object. Following that cohort for the next six weeks is specified in the cohortsRange
object.
For examples, see Cohort Report Examples.
The report response could show a weekly time series where say your app has retained 60% of this cohort after three weeks and 25% of this cohort after six weeks. These two percentages can be calculated by the metric cohortActiveUsers/cohortTotalUsers
and will be separate rows in the report.
JSON representation |
---|
{ "cohorts": [ { object ( |
Fields | |
---|---|
cohorts[] |
Defines the selection criteria to group users into cohorts. Most cohort reports define only a single cohort. If multiple cohorts are specified, each cohort can be recognized in the report by their name. |
cohorts |
Cohort reports follow cohorts over an extended reporting date range. This range specifies an offset duration to follow the cohorts over. |
cohort |
Optional settings for a cohort report. |
Cohort
Defines a cohort selection criteria. A cohort is a group of users who share a common characteristic. For example, users with the same firstSessionDate
belong to the same cohort.
JSON representation |
---|
{
"name": string,
"dimension": string,
"dateRange": {
object ( |
Fields | |
---|---|
name |
Assigns a name to this cohort. The dimension |
dimension |
Dimension used by the cohort. Required and only supports |
date |
The cohort selects users whose first touch date is between start date and end date defined in the In a cohort request, this This |
CohortsRange
Configures the extended reporting date range for a cohort report. Specifies an offset duration to follow the cohorts over.
JSON representation |
---|
{
"granularity": enum ( |
Fields | |
---|---|
granularity |
Required. The granularity used to interpret the |
start |
If If If |
end |
Required. If If If |
Granularity
The granularity used to interpret the startOffset
and endOffset
for the extended reporting date range for a cohort report.
Enums | |
---|---|
GRANULARITY_UNSPECIFIED |
Should never be specified. |
DAILY |
Daily granularity. Commonly used if the cohort's dateRange is a single day and the request contains cohortNthDay . |
WEEKLY |
Weekly granularity. Commonly used if the cohort's dateRange is a week in duration (starting on Sunday and ending on Saturday) and the request contains cohortNthWeek . |
MONTHLY |
Monthly granularity. Commonly used if the cohort's dateRange is a month in duration and the request contains cohortNthMonth . |
CohortReportSettings
Optional settings of a cohort report.
JSON representation |
---|
{ "accumulate": boolean } |
Fields | |
---|---|
accumulate |
If true, accumulates the result from first touch day to the end day. Not supported in |
SamplingLevel
Categories of sampling levels for the requests.
Enums | |
---|---|
SAMPLING_LEVEL_UNSPECIFIED |
Unspecified type. |
LOW |
Applies a sampling level of 10 million to standard properties and 100 million to Google Analytics 360 properties. |
MEDIUM |
Exclusive to Google Analytics 360 properties with a sampling level of 1 billion. |
UNSAMPLED |
Exclusive to Google Analytics 360 properties. Unsampled explorations more accurate and can reveal insights that aren't visible in standard explorations. To learn more, see https://support.google.com/analytics/answer/10896953. |
ReportMetadata
The report metadata for a specific report task.
JSON representation |
---|
{
"creationQuotaTokensCharged": integer,
"state": enum ( |
Fields | |
---|---|
creation |
Output only. The total quota tokens charged during creation of the report. Because this token count is based on activity from the |
state |
Output only. The current state for this report task. |
begin |
Output only. The time when A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: |
task |
Output only. The total number of rows in the report result. This field will be populated when the state is active. You can utilize |
error |
Output only. Error message is populated if a report task fails during creation. |
total |
Output only. The total number of rows in Google Analytics storage. If you want to query additional data rows beyond the current report, they can initiate a new report task based on the The For example, suppose the current report's |
State
The processing state.
Enums | |
---|---|
STATE_UNSPECIFIED |
Unspecified state will never be used. |
CREATING |
The report is currently creating and will be available in the future. Creating occurs immediately after the CreateReport call. |
ACTIVE |
The report is fully created and ready for querying. |
FAILED |
The report failed to be created. |
Methods |
|
---|---|
|
Initiates the creation of a report task. |
|
Gets report metadata about a specific report task. |
|
Lists all report tasks for a property. |
|
Retrieves a report task's content. |