data-plane-api 0.1.1

// Copyright 2022 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.v1beta;

import "google/analytics/data/v1beta/data.proto";
import "google/api/annotations.proto";
import "google/api/client.proto";
import "google/api/field_behavior.proto";
import "google/api/resource.proto";

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

// Google Analytics reporting data service.
service BetaAnalyticsData {
  option (google.api.default_host) = "analyticsdata.googleapis.com";
  option (google.api.oauth_scopes) =
      "https://www.googleapis.com/auth/analytics,"
      "https://www.googleapis.com/auth/analytics.readonly";

  // Returns a customized report of your Google Analytics event data. Reports
  // contain statistics derived from data collected by the Google Analytics
  // tracking code. The data returned from the API is as a table with columns
  // for the requested dimensions and metrics. Metrics are individual
  // measurements of user activity on your property, such as active users or
  // event count. Dimensions break down metrics across some common criteria,
  // such as country or event name.
  //
  // For a guide to constructing requests & understanding responses, see
  // [Creating a
  // Report](https://developers.google.com/analytics/devguides/reporting/data/v1/basics).
  rpc RunReport(RunReportRequest) returns (RunReportResponse) {
    option (google.api.http) = {
      post: "/v1beta/{property=properties/*}:runReport"
      body: "*"
    };
  }

  // Returns a customized pivot report of your Google Analytics event data.
  // Pivot reports are more advanced and expressive formats than regular
  // reports. In a pivot report, dimensions are only visible if they are
  // included in a pivot. Multiple pivots can be specified to further dissect
  // your data.
  rpc RunPivotReport(RunPivotReportRequest) returns (RunPivotReportResponse) {
    option (google.api.http) = {
      post: "/v1beta/{property=properties/*}:runPivotReport"
      body: "*"
    };
  }

  // Returns multiple reports in a batch. All reports must be for the same
  // GA4 Property.
  rpc BatchRunReports(BatchRunReportsRequest) returns (BatchRunReportsResponse) {
    option (google.api.http) = {
      post: "/v1beta/{property=properties/*}:batchRunReports"
      body: "*"
    };
  }

  // Returns multiple pivot reports in a batch. All reports must be for the same
  // GA4 Property.
  rpc BatchRunPivotReports(BatchRunPivotReportsRequest) returns (BatchRunPivotReportsResponse) {
    option (google.api.http) = {
      post: "/v1beta/{property=properties/*}:batchRunPivotReports"
      body: "*"
    };
  }

  // Returns metadata for dimensions and metrics available in reporting methods.
  // Used to explore the dimensions and metrics. In this method, a Google
  // Analytics GA4 Property Identifier is specified in the request, and
  // the metadata response includes Custom dimensions and metrics as well as
  // Universal metadata.
  //
  // For example if a custom metric with parameter name `levels_unlocked` is
  // registered to a property, the Metadata response will contain
  // `customEvent:levels_unlocked`. Universal metadata are dimensions and
  // metrics applicable to any property such as `country` and `totalUsers`.
  rpc GetMetadata(GetMetadataRequest) returns (Metadata) {
    option (google.api.http) = {
      get: "/v1beta/{name=properties/*/metadata}"
    };
    option (google.api.method_signature) = "name";
  }

  // Returns a customized report of realtime event data for your property.
  // Events appear in realtime reports seconds after they have been sent to
  // the Google Analytics. Realtime reports show events and usage data for the
  // periods of time ranging from the present moment to 30 minutes ago (up to
  // 60 minutes for Google Analytics 360 properties).
  //
  // For a guide to constructing realtime requests & understanding responses,
  // see [Creating a Realtime
  // Report](https://developers.google.com/analytics/devguides/reporting/data/v1/realtime-basics).
  rpc RunRealtimeReport(RunRealtimeReportRequest) returns (RunRealtimeReportResponse) {
    option (google.api.http) = {
      post: "/v1beta/{property=properties/*}:runRealtimeReport"
      body: "*"
    };
  }

  // This compatibility method lists dimensions and metrics that can be added to
  // a report request and maintain compatibility. This method fails if the
  // request's dimensions and metrics are incompatible.
  //
  // In Google Analytics, reports fail if they request incompatible dimensions
  // and/or metrics; in that case, you will need to remove dimensions and/or
  // metrics from the incompatible report until the report is compatible.
  //
  // The Realtime and Core reports have different compatibility rules. This
  // method checks compatibility for Core reports.
  rpc CheckCompatibility(CheckCompatibilityRequest) returns (CheckCompatibilityResponse) {
    option (google.api.http) = {
      post: "/v1beta/{property=properties/*}:checkCompatibility"
      body: "*"
    };
  }
}

// The request for compatibility information for a report's dimensions and
// metrics. Check compatibility provides a preview of the compatibility of a
// report; fields shared with the `runReport` request should be the same values
// as in your `runReport` request.
message CheckCompatibilityRequest {
  // A Google Analytics GA4 property identifier whose events are tracked. To
  // learn more, see [where to find your Property
  // ID](https://developers.google.com/analytics/devguides/reporting/data/v1/property-id).
  // `property` should be the same value as in your `runReport` request.
  //
  // Example: properties/1234
  //
  // Set the Property ID to 0 for compatibility checking on dimensions and
  // metrics common to all properties. In this special mode, this method will
  // not return custom dimensions and metrics.
  string property = 1;

  // The dimensions in this report. `dimensions` should be the same value as in
  // your `runReport` request.
  repeated Dimension dimensions = 2;

  // The metrics in this report. `metrics` should be the same value as in your
  // `runReport` request.
  repeated Metric metrics = 3;

  // The filter clause of dimensions. `dimensionFilter` should be the same value
  // as in your `runReport` request.
  FilterExpression dimension_filter = 4;

  // The filter clause of metrics. `metricFilter` should be the same value as in
  // your `runReport` request
  FilterExpression metric_filter = 5;

  // Filters the dimensions and metrics in the response to just this
  // compatibility. Commonly used as `”compatibilityFilter”: “COMPATIBLE”`
  // to only return compatible dimensions & metrics.
  Compatibility compatibility_filter = 6;
}

// The compatibility response with the compatibility of each dimension & metric.
message CheckCompatibilityResponse {
  // The compatibility of each dimension.
  repeated DimensionCompatibility dimension_compatibilities = 1;

  // The compatibility of each metric.
  repeated MetricCompatibility metric_compatibilities = 2;
}

// The dimensions and metrics currently accepted in reporting methods.
message Metadata {
  option (google.api.resource) = {
    type: "analyticsdata.googleapis.com/Metadata"
    pattern: "properties/{property}/metadata"
  };

  // Resource name of this metadata.
  string name = 3;

  // The dimension descriptions.
  repeated DimensionMetadata dimensions = 1;

  // The metric descriptions.
  repeated MetricMetadata metrics = 2;
}

// The request to generate a report.
message RunReportRequest {
  // A Google Analytics GA4 property identifier whose events are tracked.
  // Specified in the URL path and not the body. To learn more, see [where to
  // find your Property
  // ID](https://developers.google.com/analytics/devguides/reporting/data/v1/property-id).
  // Within a batch request, this property should either be unspecified or
  // consistent with the batch-level property.
  //
  // Example: properties/1234
  string property = 1;

  // The dimensions requested and displayed.
  repeated Dimension dimensions = 2;

  // The metrics requested and displayed.
  repeated Metric metrics = 3;

  // 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 `dateRanges`
  // must be unspecified.
  repeated DateRange date_ranges = 4;

  // Dimension filters allow you to ask for only specific dimension values in
  // the report. To learn more, see [Fundamentals of Dimension
  // Filters](https://developers.google.com/analytics/devguides/reporting/data/v1/basics#dimension_filters)
  // for examples. Metrics cannot be used in this filter.
  FilterExpression dimension_filter = 5;

  // The filter clause of metrics. Applied after aggregating the report's rows,
  // similar to SQL having-clause. Dimensions cannot be used in this filter.
  FilterExpression metric_filter = 6;

  // The row count of the start row. The first row is counted as row 0.
  //
  // When paging, the first request does not specify offset; or equivalently,
  // sets offset to 0; the first request returns the first `limit` of rows. The
  // second request sets offset to the `limit` of the first request; the second
  // request returns the second `limit` of rows.
  //
  // To learn more about this pagination parameter, see
  // [Pagination](https://developers.google.com/analytics/devguides/reporting/data/v1/basics#pagination).
  int64 offset = 7;

  // The number of rows to return. If unspecified, 10,000 rows are returned. The
  // API returns a maximum of 100,000 rows per request, no matter how many you
  // ask for. `limit` must be positive.
  //
  // The API can also return fewer rows than the requested `limit`, if there
  // aren't as many dimension values as the `limit`. For instance, there are
  // fewer than 300 possible values for the dimension `country`, so when
  // reporting on only `country`, you can't get more than 300 rows, even if you
  // set `limit` to a higher value.
  //
  // To learn more about this pagination parameter, see
  // [Pagination](https://developers.google.com/analytics/devguides/reporting/data/v1/basics#pagination).
  int64 limit = 8;

  // Aggregation of metrics. Aggregated metric values will be shown in rows
  // where the dimension_values are set to "RESERVED_(MetricAggregation)".
  repeated MetricAggregation metric_aggregations = 9;

  // Specifies how rows are ordered in the response.
  repeated OrderBy order_bys = 10;

  // A currency code in ISO4217 format, such as "AED", "USD", "JPY".
  // If the field is empty, the report uses the property's default currency.
  string currency_code = 11;

  // Cohort group associated with this request. If there is a cohort group
  // in the request the 'cohort' dimension must be present.
  CohortSpec cohort_spec = 12;

  // 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.
  bool keep_empty_rows = 13;

  // Toggles whether to return the current state of this Analytics Property's
  // quota. Quota is returned in [PropertyQuota](#PropertyQuota).
  bool return_property_quota = 14;
}

// The response report table corresponding to a request.
message RunReportResponse {
  // Describes dimension columns. The number of DimensionHeaders and ordering of
  // DimensionHeaders matches the dimensions present in rows.
  repeated DimensionHeader dimension_headers = 1;

  // Describes metric columns. The number of MetricHeaders and ordering of
  // MetricHeaders matches the metrics present in rows.
  repeated MetricHeader metric_headers = 2;

  // Rows of dimension value combinations and metric values in the report.
  repeated Row rows = 3;

  // If requested, the totaled values of metrics.
  repeated Row totals = 4;

  // If requested, the maximum values of metrics.
  repeated Row maximums = 5;

  // If requested, the minimum values of metrics.
  repeated Row minimums = 6;

  // The total number of rows in the query result. `rowCount` is independent of
  // the number of rows returned in the response, the `limit` request
  // parameter, and the `offset` request parameter. For example if a query
  // returns 175 rows and includes `limit` of 50 in the API request, the
  // response will contain `rowCount` of 175 but only 50 rows.
  //
  // To learn more about this pagination parameter, see
  // [Pagination](https://developers.google.com/analytics/devguides/reporting/data/v1/basics#pagination).
  int32 row_count = 7;

  // Metadata for the report.
  ResponseMetaData metadata = 8;

  // This Analytics Property's quota state including this request.
  PropertyQuota property_quota = 9;

  // Identifies what kind of resource this message is. This `kind` is always the
  // fixed string "analyticsData#runReport". Useful to distinguish between
  // response types in JSON.
  string kind = 10;
}

// The request to generate a pivot report.
message RunPivotReportRequest {
  // A Google Analytics GA4 property identifier whose events are tracked.
  // Specified in the URL path and not the body. To learn more, see [where to
  // find your Property
  // ID](https://developers.google.com/analytics/devguides/reporting/data/v1/property-id).
  // Within a batch request, this property should either be unspecified or
  // consistent with the batch-level property.
  //
  // Example: properties/1234
  string property = 1;

  // The dimensions requested. All defined dimensions must be used by one of the
  // following: dimension_expression, dimension_filter, pivots, order_bys.
  repeated Dimension dimensions = 2;

  // The metrics requested, at least one metric needs to be specified. All
  // defined metrics must be used by one of the following: metric_expression,
  // metric_filter, order_bys.
  repeated Metric metrics = 3;

  // The date range to retrieve event data for the report. If multiple date
  // ranges are specified, event data from each date range is used in the
  // report. A special dimension with field name "dateRange" can be included in
  // a Pivot's field names; if included, the report compares between date
  // ranges. In a cohort request, this `dateRanges` must be unspecified.
  repeated DateRange date_ranges = 4;

  // Describes the visual format of the report's dimensions in columns or rows.
  // The union of the fieldNames (dimension names) in all pivots must be a
  // subset of dimension names defined in Dimensions. No two pivots can share a
  // dimension. A dimension is only visible if it appears in a pivot.
  repeated Pivot pivots = 5;

  // The filter clause of dimensions. Dimensions must be requested to be used in
  // this filter. Metrics cannot be used in this filter.
  FilterExpression dimension_filter = 6;

  // The filter clause of metrics. Applied at post aggregation phase, similar to
  // SQL having-clause. Metrics must be requested to be used in this filter.
  // Dimensions cannot be used in this filter.
  FilterExpression metric_filter = 7;

  // A currency code in ISO4217 format, such as "AED", "USD", "JPY".
  // If the field is empty, the report uses the property's default currency.
  string currency_code = 8;

  // Cohort group associated with this request. If there is a cohort group
  // in the request the 'cohort' dimension must be present.
  CohortSpec cohort_spec = 9;

  // 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.
  bool keep_empty_rows = 10;

  // Toggles whether to return the current state of this Analytics Property's
  // quota. Quota is returned in [PropertyQuota](#PropertyQuota).
  bool return_property_quota = 11;
}

// The response pivot report table corresponding to a pivot request.
message RunPivotReportResponse {
  // Summarizes the columns and rows created by a pivot. Each pivot in the
  // request produces one header in the response. If we have a request like
  // this:
  //
  //     "pivots": [{
  //       "fieldNames": ["country",
  //         "city"]
  //     },
  //     {
  //       "fieldNames": "eventName"
  //     }]
  //
  // We will have the following `pivotHeaders` in the response:
  //
  //     "pivotHeaders" : [{
  //       "dimensionHeaders": [{
  //         "dimensionValues": [
  //            { "value": "United Kingdom" },
  //            { "value": "London" }
  //          ]
  //       },
  //       {
  //         "dimensionValues": [
  //         { "value": "Japan" },
  //         { "value": "Osaka" }
  //         ]
  //       }]
  //     },
  //     {
  //       "dimensionHeaders": [{
  //         "dimensionValues": [{ "value": "session_start" }]
  //       },
  //       {
  //         "dimensionValues": [{ "value": "scroll" }]
  //       }]
  //     }]
  repeated PivotHeader pivot_headers = 1;

  // Describes dimension columns. The number of DimensionHeaders and ordering of
  // DimensionHeaders matches the dimensions present in rows.
  repeated DimensionHeader dimension_headers = 2;

  // Describes metric columns. The number of MetricHeaders and ordering of
  // MetricHeaders matches the metrics present in rows.
  repeated MetricHeader metric_headers = 3;

  // Rows of dimension value combinations and metric values in the report.
  repeated Row rows = 4;

  // Aggregation of metric values. Can be totals, minimums, or maximums. The
  // returned aggregations are controlled by the metric_aggregations in the
  // pivot. The type of aggregation returned in each row is shown by the
  // dimension_values which are set to "RESERVED_<MetricAggregation>".
  repeated Row aggregates = 5;

  // Metadata for the report.
  ResponseMetaData metadata = 6;

  // This Analytics Property's quota state including this request.
  PropertyQuota property_quota = 7;

  // Identifies what kind of resource this message is. This `kind` is always the
  // fixed string "analyticsData#runPivotReport". Useful to distinguish between
  // response types in JSON.
  string kind = 8;
}

// The batch request containing multiple report requests.
message BatchRunReportsRequest {
  // A Google Analytics GA4 property identifier whose events are tracked.
  // Specified in the URL path and not the body. To learn more, see [where to
  // find your Property
  // ID](https://developers.google.com/analytics/devguides/reporting/data/v1/property-id).
  // This property must be specified for the batch. The property within
  // RunReportRequest may either be unspecified or consistent with this
  // property.
  //
  // Example: properties/1234
  string property = 1;

  // Individual requests. Each request has a separate report response. Each
  // batch request is allowed up to 5 requests.
  repeated RunReportRequest requests = 2;
}

// The batch response containing multiple reports.
message BatchRunReportsResponse {
  // Individual responses. Each response has a separate report request.
  repeated RunReportResponse reports = 1;

  // Identifies what kind of resource this message is. This `kind` is always the
  // fixed string "analyticsData#batchRunReports". Useful to distinguish between
  // response types in JSON.
  string kind = 2;
}

// The batch request containing multiple pivot report requests.
message BatchRunPivotReportsRequest {
  // A Google Analytics GA4 property identifier whose events are tracked.
  // Specified in the URL path and not the body. To learn more, see [where to
  // find your Property
  // ID](https://developers.google.com/analytics/devguides/reporting/data/v1/property-id).
  // This property must be specified for the batch. The property within
  // RunPivotReportRequest may either be unspecified or consistent with this
  // property.
  //
  // Example: properties/1234
  string property = 1;

  // Individual requests. Each request has a separate pivot report response.
  // Each batch request is allowed up to 5 requests.
  repeated RunPivotReportRequest requests = 2;
}

// The batch response containing multiple pivot reports.
message BatchRunPivotReportsResponse {
  // Individual responses. Each response has a separate pivot report request.
  repeated RunPivotReportResponse pivot_reports = 1;

  // Identifies what kind of resource this message is. This `kind` is always the
  // fixed string "analyticsData#batchRunPivotReports". Useful to distinguish
  // between response types in JSON.
  string kind = 2;
}

// Request for a property's dimension and metric metadata.
message GetMetadataRequest {
  // Required. The resource name of the metadata to retrieve. This name field is
  // specified in the URL path and not URL parameters. Property is a numeric
  // Google Analytics GA4 Property identifier. To learn more, see [where to find
  // your Property
  // ID](https://developers.google.com/analytics/devguides/reporting/data/v1/property-id).
  //
  // Example: properties/1234/metadata
  //
  // Set the Property ID to 0 for dimensions and metrics common to all
  // properties. In this special mode, this method will not return custom
  // dimensions and metrics.
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "analyticsdata.googleapis.com/Metadata"
    }
  ];
}

// The request to generate a realtime report.
message RunRealtimeReportRequest {
  // A Google Analytics GA4 property identifier whose events are tracked.
  // Specified in the URL path and not the body. To learn more, see [where to
  // find your Property
  // ID](https://developers.google.com/analytics/devguides/reporting/data/v1/property-id).
  //
  // Example: properties/1234
  string property = 1;

  // The dimensions requested and displayed.
  repeated Dimension dimensions = 2;

  // The metrics requested and displayed.
  repeated Metric metrics = 3;

  // The filter clause of dimensions. Metrics cannot be used in this filter.
  FilterExpression dimension_filter = 4;

  // The filter clause of metrics. Applied at post aggregation phase, similar to
  // SQL having-clause. Dimensions cannot be used in this filter.
  FilterExpression metric_filter = 5;

  // The number of rows to return. If unspecified, 10,000 rows are returned. The
  // API returns a maximum of 100,000 rows per request, no matter how many you
  // ask for. `limit` must be positive.
  //
  // The API can also return fewer rows than the requested `limit`, if there
  // aren't as many dimension values as the `limit`. For instance, there are
  // fewer than 300 possible values for the dimension `country`, so when
  // reporting on only `country`, you can't get more than 300 rows, even if you
  // set `limit` to a higher value.
  int64 limit = 6;

  // Aggregation of metrics. Aggregated metric values will be shown in rows
  // where the dimension_values are set to "RESERVED_(MetricAggregation)".
  repeated MetricAggregation metric_aggregations = 7;

  // Specifies how rows are ordered in the response.
  repeated OrderBy order_bys = 8;

  // Toggles whether to return the current state of this Analytics Property's
  // Realtime quota. Quota is returned in [PropertyQuota](#PropertyQuota).
  bool return_property_quota = 9;

  // The minute ranges of event data to read. If unspecified, one minute range
  // for the last 30 minutes will be used. If multiple minute ranges are
  // requested, each response row will contain a zero based minute range index.
  // If two minute ranges overlap, the event data for the overlapping minutes is
  // included in the response rows for both minute ranges.
  repeated MinuteRange minute_ranges = 10;
}

// The response realtime report table corresponding to a request.
message RunRealtimeReportResponse {
  // Describes dimension columns. The number of DimensionHeaders and ordering of
  // DimensionHeaders matches the dimensions present in rows.
  repeated DimensionHeader dimension_headers = 1;

  // Describes metric columns. The number of MetricHeaders and ordering of
  // MetricHeaders matches the metrics present in rows.
  repeated MetricHeader metric_headers = 2;

  // Rows of dimension value combinations and metric values in the report.
  repeated Row rows = 3;

  // If requested, the totaled values of metrics.
  repeated Row totals = 4;

  // If requested, the maximum values of metrics.
  repeated Row maximums = 5;

  // If requested, the minimum values of metrics.
  repeated Row minimums = 6;

  // The total number of rows in the query result. `rowCount` is independent of
  // the number of rows returned in the response and the `limit` request
  // parameter. For example if a query returns 175 rows and includes `limit`
  // of 50 in the API request, the response will contain `rowCount` of 175 but
  // only 50 rows.
  int32 row_count = 7;

  // This Analytics Property's Realtime quota state including this request.
  PropertyQuota property_quota = 8;

  // Identifies what kind of resource this message is. This `kind` is always the
  // fixed string "analyticsData#runRealtimeReport". Useful to distinguish
  // between response types in JSON.
  string kind = 9;
}