data.proto

// Copyright 2020 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

package google.analytics.data.v1alpha;

option go_package = "google.golang.org/genproto/googleapis/analytics/data/v1alpha;data";
option java_multiple_files = true;
option java_outer_classname = "ReportingApiProto";
option java_package = "com.google.analytics.data.v1alpha";

// A contiguous set of days: startDate, startDate + 1, ..., endDate. Requests
// are allowed up to 4 date ranges, and the union of the ranges can cover up to
// 1 year.
message DateRange {
  // The inclusive start date for the query in the format `YYYY-MM-DD`. Cannot
  // be after `end_date`. The format `NdaysAgo`, `yesterday`, or `today` is also
  // accepted, and in that case, the date is inferred based on the property's
  // reporting time zone.
  string start_date = 1;

  // The inclusive end date for the query in the format `YYYY-MM-DD`. Cannot
  // be before `start_date`. The format `NdaysAgo`, `yesterday`, or `today` is
  // also accepted, and in that case, the date is inferred based on the
  // property's reporting time zone.
  string end_date = 2;

  // Assigns a name to this date range. The dimension `dateRange` is valued to
  // this name in a report response. If set, cannot begin with `date_range_` or
  // `RESERVED_`. If not set, date ranges are named by their zero based index in
  // the request: `date_range_0`, `date_range_1`, etc.
  string name = 3;
}

// The unique identifier of the property whose events are tracked.
message Entity {
  // A Google Analytics App + Web property id.
  string property_id = 1;
}

// Dimensions are attributes of your data. For example, the dimension City
// indicates the city, for example, "Paris" or "New York", from which an event
// originates. Requests are allowed up to 8 dimensions.
message Dimension {
  // The name of the dimension.
  string name = 1;

  // One dimension can be the result of an expression of multiple dimensions.
  // For example, dimension "country, city": concatenate(country, ", ", city).
  DimensionExpression dimension_expression = 2;
}

// Used to express a dimension which is the result of a formula of multiple
// dimensions. Example usages:
// 1) lower_case(dimension)
// 2) concatenate(dimension1, symbol, dimension2).
message DimensionExpression {
  // Used to convert a dimension value to a single case.
  message CaseExpression {
    // Name of a dimension. The name must refer back to a name in dimensions
    // field of the request.
    string dimension_name = 1;
  }

  // Used to combine dimension values to a single dimension.
  message ConcatenateExpression {
    // Names of dimensions. The names must refer back to names in the dimensions
    // field of the request.
    repeated string dimension_names = 1;

    // 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".
    string delimiter = 2;
  }

  // Specify one type of dimension expression for `DimensionExpression`.
  oneof one_expression {
    // Used to convert a dimension value to lower case.
    CaseExpression lower_case = 4;

    // Used to convert a dimension value to upper case.
    CaseExpression upper_case = 5;

    // Used to combine dimension values to a single dimension.
    // For example, dimension "country, city": concatenate(country, ", ", city).
    ConcatenateExpression concatenate = 6;
  }
}

// The quantitative measurements of a report. For example, the metric eventCount
// is the total number of events. Requests are allowed up to 10 metrics.
message Metric {
  // The name of the metric.
  string name = 1;

  // A mathematical expression for derived metrics. For example, the metric
  // Event count per user is eventCount/totalUsers.
  string expression = 2;

  // Indicates if a metric is invisible.
  // If a metric is invisible, the metric is not in the response, but can be
  // used in filters, order_bys or being referred to in a metric expression.
  bool invisible = 3;
}

// To express dimension or metric filters.
// The fields in the same FilterExpression need to be either all dimensions or
// all metrics.
message FilterExpression {
  // Specify one type of filter expression for `FilterExpression`.
  oneof expr {
    // The FilterExpressions in and_group have an AND relationship.
    FilterExpressionList and_group = 1;

    // The FilterExpressions in or_group have an OR relationship.
    FilterExpressionList or_group = 2;

    // The FilterExpression is NOT of not_expression.
    FilterExpression not_expression = 3;

    // A primitive filter.
    // All fields in filter in same FilterExpression needs to be either all
    // dimensions or metrics.
    Filter filter = 4;
  }
}

// A list of filter expressions.
message FilterExpressionList {
  // A list of filter expressions.
  repeated FilterExpression expressions = 1;
}

// An expression to filter dimension or metric values.
message Filter {
  // The filter for string
  message StringFilter {
    // The match type of a string filter
    enum MatchType {
      // Unspecified
      MATCH_TYPE_UNSPECIFIED = 0;

      // Exact match of the string value.
      EXACT = 1;

      // Begins with the string value.
      BEGINS_WITH = 2;

      // Ends with the string value.
      ENDS_WITH = 3;

      // Contains the string value.
      CONTAINS = 4;

      // Full regular expression match with the string value.
      FULL_REGEXP = 5;

      // Partial regular expression match with the string value.
      PARTIAL_REGEXP = 6;
    }

    // The match type for this filter.
    MatchType match_type = 1;

    // The string value used for the matching.
    string value = 2;

    // If true, the string value is case sensitive.
    bool case_sensitive = 3;
  }

  // The result needs to be in a list of string values.
  message InListFilter {
    // The list of string values.
    // Must be non-empty.
    repeated string values = 1;

    // If true, the string value is case sensitive.
    bool case_sensitive = 2;
  }

  // Filters for numeric or date values.
  message NumericFilter {
    // The operation applied to a numeric filter
    enum Operation {
      // Unspecified.
      OPERATION_UNSPECIFIED = 0;

      // Equal
      EQUAL = 1;

      // Less than
      LESS_THAN = 2;

      // Less than or equal
      LESS_THAN_OR_EQUAL = 3;

      // Greater than
      GREATER_THAN = 4;

      // Greater than or equal
      GREATER_THAN_OR_EQUAL = 5;
    }

    // The operation type for this filter.
    Operation operation = 1;

    // A numeric value or a date value.
    NumericValue value = 2;
  }

  // To express that the result needs to be between two numbers (inclusive).
  message BetweenFilter {
    // Begins with this number.
    NumericValue from_value = 1;

    // Ends with this number.
    NumericValue to_value = 2;
  }

  // The dimension name or metric name. Must be a name defined in dimensions
  // or metrics.
  string field_name = 1;

  // Specify one type of filter for `Filter`.
  oneof one_filter {
    // A filter for null values.
    bool null_filter = 2;

    // Strings related filter.
    StringFilter string_filter = 3;

    // A filter for in list values.
    InListFilter in_list_filter = 4;

    // A filter for numeric or date values.
    NumericFilter numeric_filter = 5;

    // A filter for two values.
    BetweenFilter between_filter = 6;
  }
}

// The sort options.
message OrderBy {
  // Sorts by metric values.
  message MetricOrderBy {
    // A metric name in the request to order by.
    string metric_name = 1;
  }

  // Sorts by dimension values.
  message DimensionOrderBy {
    // Rule to order the string dimension values by.
    enum OrderType {
      // Unspecified.
      ORDER_TYPE_UNSPECIFIED = 0;

      // Alphanumeric sort by Unicode code point. For example, "2" < "A" < "X" <
      // "b" < "z".
      ALPHANUMERIC = 1;

      // Case insensitive alphanumeric sort by lower case Unicode code point.
      // For example, "2" < "A" < "b" < "X" < "z".
      CASE_INSENSITIVE_ALPHANUMERIC = 2;

      // 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.
      NUMERIC = 3;
    }

    // A dimension name in the request to order by.
    string dimension_name = 1;

    // Controls the rule for dimension value ordering.
    OrderType order_type = 2;
  }

  // Sorts by a pivot column group.
  message PivotOrderBy {
    // A pair of dimension names and values. Rows with this dimension pivot pair
    // are ordered by the metric's value.
    //
    // For example if pivots = {{"browser", "Chrome"}} and
    // metric_name = "Sessions",
    // then the rows will be sorted based on Sessions in Chrome.
    //
    //     ---------|----------|----------------|----------|----------------
    //              |  Chrome  |    Chrome      |  Safari  |     Safari
    //     ---------|----------|----------------|----------|----------------
    //      Country | Sessions | Pages/Sessions | Sessions | Pages/Sessions
    //     ---------|----------|----------------|----------|----------------
    //         US   |    2     |       2        |     3    |        1
    //     ---------|----------|----------------|----------|----------------
    //       Canada |    3     |       1        |     4    |        1
    //     ---------|----------|----------------|----------|----------------
    message PivotSelection {
      // Must be a dimension name from the request.
      string dimension_name = 1;

      // Order by only when the named dimension is this value.
      string dimension_value = 2;
    }

    // In the response to order by, order rows by this column. Must be a metric
    // name from the request.
    string metric_name = 1;

    // Used to select a dimension name and value pivot. If multiple pivot
    // selections are given, the sort occurs on rows where all pivot selection
    // dimension name and value pairs match the row's dimension name and value
    // pair.
    repeated PivotSelection pivot_selections = 2;
  }

  // Specify one type of order by for `OrderBy`.
  oneof one_order_by {
    // Sorts results by a metric's values.
    MetricOrderBy metric = 1;

    // Sorts results by a dimension's values.
    DimensionOrderBy dimension = 2;

    // Sorts results by a metric's values within a pivot column group.
    PivotOrderBy pivot = 3;
  }

  // If true, sorts by descending order.
  bool desc = 4;
}

// Describes the visible dimension columns and rows in the report response.
message Pivot {
  // Dimension names for visible columns in the report response. Including
  // "dateRange" produces a date range column; for each row in the response,
  // dimension values in the date range column will indicate the corresponding
  // date range from the request.
  repeated string field_names = 1;

  // Specifies how dimensions are ordered in the pivot. In the first Pivot, the
  // OrderBys determine Row and PivotDimensionHeader ordering; in subsequent
  // Pivots, the OrderBys determine only PivotDimensionHeader ordering.
  // Dimensions specified in these OrderBys must be a subset of
  // Pivot.field_names.
  repeated OrderBy order_bys = 2;

  // The row count of the start row. The first row is counted as row 0.
  int64 offset = 3;

  // The number of rows to return in this pivot. If unspecified, 10 rows are
  // returned. If -1, all rows are returned.
  int64 limit = 4;

  // Aggregate the metrics by dimensions in this pivot using the specified
  // metric_aggregations.
  repeated MetricAggregation metric_aggregations = 5;
}

// Specification for a cohort report.
message CohortSpec {
  // The definition for the cohorts.
  repeated Cohort cohorts = 1;

  // The data ranges of cohorts.
  CohortsRange cohorts_range = 2;

  // Settings of a cohort report.
  CohortReportSettings cohort_report_settings = 3;
}

// Defines a cohort. A cohort is a group of users who share a common
// characteristic. For example, all users with the same acquisition date
// belong to the same cohort.
message Cohort {
  // Assigns a name to this cohort. The dimension `cohort` is valued to this
  // name in a report response. If set, cannot begin with `cohort_` or
  // `RESERVED_`. If not set, cohorts are named by their zero based index
  // `cohort_0`, `cohort_1`, etc.
  string name = 1;

  // The dimension used by cohort. Only supports `firstTouchDate` for retention
  // report.
  string dimension = 2;

  // The cohort selects users whose first visit date is between start date
  // and end date defined in the `dateRange`. In a cohort request, this
  // `dateRange` is required and the `dateRanges` in the `RunReportRequest` or
  // `RunPivotReportRequest` must be unspecified.
  //
  // The date range should be aligned with the cohort's granularity. If
  // CohortsRange uses daily granularity, the date range can be aligned to any
  // day. If CohortsRange uses weekly granularity, the date range should be
  // aligned to the week boundary, starting at Sunday and ending Saturday. If
  // CohortsRange uses monthly granularity, the date range should be aligned to
  // the month, starting at the first and ending on the last day of the month.
  DateRange date_range = 3;
}

// Settings of a cohort report.
message CohortReportSettings {
  // If true, accumulates the result from first visit day to the end day. Not
  // supported in `RunReportRequest`.
  bool accumulate = 1;
}

// Describes date range for a cohort report.
message CohortsRange {
  // Reporting granularity for the cohorts.
  enum Granularity {
    // Unspecified.
    GRANULARITY_UNSPECIFIED = 0;

    // Daily
    DAILY = 1;

    // Weekly
    WEEKLY = 2;

    // Monthly
    MONTHLY = 3;
  }

  // Reporting date range for each cohort is calculated based on these three
  // fields.
  Granularity granularity = 1;

  // For daily cohorts, this will be the start day offset.
  // For weekly cohorts, this will be the week offset.
  int32 start_offset = 2;

  // For daily cohorts, this will be the end day offset.
  // For weekly cohorts, this will be the week offset.
  int32 end_offset = 3;
}

// Response's metadata carrying additional information about the report content.
message ResponseMetaData {
  // If true, indicates some buckets of dimension combinations are rolled into
  // "(other)" row. This can happen for high cardinality reports.
  bool data_loss_from_other_row = 3;
}

// Describes a dimension column in the report. Dimensions requested in a report
// produce column entries within rows and DimensionHeaders. However, dimensions
// used exclusively within filters or expressions do not produce columns in a
// report; correspondingly, those dimensions do not produce headers.
message DimensionHeader {
  // The dimension's name.
  string name = 1;
}

// Describes a metric column in the report. Visible metrics requested in a
// report produce column entries within rows and MetricHeaders. However,
// metrics used exclusively within filters or expressions do not produce columns
// in a report; correspondingly, those metrics do not produce headers.
message MetricHeader {
  // The metric's name.
  string name = 1;

  // The metric's data type.
  MetricType type = 2;
}

// Dimensions' values in a single pivot.
message PivotHeader {
  // The size is the same as the cardinality of the corresponding dimension
  // combinations.
  repeated PivotDimensionHeader pivot_dimension_headers = 1;

  // The cardinality of the pivot as if offset = 0 and limit = -1. The total
  // number of rows for this pivot's fields regardless of how the parameters
  // offset and limit are specified in the request.
  int32 row_count = 2;
}

// Summarizes dimension values from a row for this pivot.
message PivotDimensionHeader {
  // Values of multiple dimensions in a pivot.
  repeated DimensionValue dimension_values = 1;
}

// Report data for each row.
// For example if RunReportRequest contains:
//
// ```none
// dimensions {
//   name: "eventName"
// }
// dimensions {
//   name: "countryId"
// }
// metrics {
//   name: "eventCount"
// }
// ```
//
// One row with 'in_app_purchase' as the eventName, 'us' as the countryId, and
// 15 as the eventCount, would be:
//
// ```none
// dimension_values {
//   name: 'in_app_purchase'
//   name: 'us'
// }
// metric_values {
//   int64_value: 15
// }
// ```
message Row {
  // List of requested dimension values. In a PivotReport, dimension_values
  // are only listed for dimensions included in a pivot.
  repeated DimensionValue dimension_values = 1;

  // List of requested visible metric values.
  repeated MetricValue metric_values = 2;
}

// The value of a dimension.
message DimensionValue {
  // One kind of dimension value
  oneof one_value {
    // Value as a string if the dimension type is a string.
    string value = 1;
  }
}

// The value of a metric.
message MetricValue {
  // One of metric value
  oneof one_value {
    // Measurement value. See MetricHeader for type.
    string value = 4;
  }
}

// To represent a number.
message NumericValue {
  // One of a numeric value
  oneof one_value {
    // Integer value
    int64 int64_value = 1;

    // Double value
    double double_value = 2;
  }
}

// Current state of all quotas for this Analytics Property. If any quota for a
// property is exhausted, all requests to that property will return Resource
// Exhausted errors.
message PropertyQuota {
  // Analytics Properties can use up to 25,000 tokens per day. Most requests
  // consume fewer than 10 tokens.
  QuotaStatus tokens_per_day = 1;

  // Analytics Properties can use up to 5,000 tokens per day. An API request
  // consumes a single number of tokens, and that number is deducted from both
  // the hourly and daily quotas.
  QuotaStatus tokens_per_hour = 2;

  // Analytics Properties can send up to 10 concurrent requests.
  QuotaStatus concurrent_requests = 3;

  // Analytics Properties and cloud project pairs can have up to 10
  // server errors per hour.
  QuotaStatus server_errors_per_project_per_hour = 4;
}

// Current state for a particular quota group.
message QuotaStatus {
  // Quota consumed by this request.
  int32 consumed = 1;

  // Quota remaining after this request.
  int32 remaining = 2;
}

// Explains a dimension.
message DimensionMetadata {
  // This dimension's name. Useable in [Dimension](#Dimension)'s `name`. For
  // example, `eventName`.
  string api_name = 1;

  // This dimension's name within the Google Analytics user interface. For
  // example, `Event name`.
  string ui_name = 2;

  // Description of how this dimension is used and calculated.
  string description = 3;

  // Still usable but deprecated names for this dimension. If populated, this
  // dimension is available by either `apiName` or one of `deprecatedApiNames`
  // for a period of time. After the deprecation period, the dimension will be
  // available only by `apiName`.
  repeated string deprecated_api_names = 4;
}

// Explains a metric.
message MetricMetadata {
  // A metric name. Useable in [Metric](#Metric)'s `name`. For example,
  // `eventCount`.
  string api_name = 1;

  // This metric's name within the Google Analytics user interface. For example,
  // `Event count`.
  string ui_name = 2;

  // Description of how this metric is used and calculated.
  string description = 3;

  // Still usable but deprecated names for this metric. If populated, this
  // metric is available by either `apiName` or one of `deprecatedApiNames`
  // for a period of time. After the deprecation period, the metric will be
  // available only by `apiName`.
  repeated string deprecated_api_names = 4;

  // The type of this metric.
  MetricType type = 5;

  // The mathematical expression for this derived metric. Can be used in
  // [Metric](#Metric)'s `expression` field for equivalent reports. Most metrics
  // are not expressions, and for non-expressions, this field is empty.
  string expression = 6;
}

// Represents aggregation of metrics.
enum MetricAggregation {
  // Unspecified operator.
  METRIC_AGGREGATION_UNSPECIFIED = 0;

  // SUM operator.
  TOTAL = 1;

  // Minimum operator.
  MINIMUM = 5;

  // Maximum operator.
  MAXIMUM = 6;

  // Count operator.
  COUNT = 4;
}

// A metric's value type.
enum MetricType {
  // Unspecified type.
  METRIC_TYPE_UNSPECIFIED = 0;

  // Integer type.
  TYPE_INTEGER = 1;

  // Floating point type.
  TYPE_FLOAT = 2;

  // A duration of seconds; a special floating point type.
  TYPE_SECONDS = 4;

  // An amount of money; a special floating point type.
  TYPE_CURRENCY = 9;
}