googleapis/google/analytics/data/v1alpha/analytics_data_api.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;

import "google/analytics/data/v1alpha/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/v1alpha;data";
option java_multiple_files = true;
option java_outer_classname = "AnalyticsDataApiProto";
option java_package = "com.google.analytics.data.v1alpha";

// Google Analytics reporting data service.
service AlphaAnalyticsData {
  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.
  rpc RunReport(RunReportRequest) returns (RunReportResponse) {
    option (google.api.http) = {
      post: "/v1alpha: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: "/v1alpha:runPivotReport"
      body: "*"
    };
  }

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

  // Returns multiple pivot reports in a batch. All reports must be for the same
  // Entity.
  rpc BatchRunPivotReports(BatchRunPivotReportsRequest) returns (BatchRunPivotReportsResponse) {
    option (google.api.http) = {
      post: "/v1alpha: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: "/v1alpha/{name=properties/*/metadata}"
    };
    option (google.api.method_signature) = "name";
  }

  // The Google Analytics Realtime API returns a customized report of realtime
  // event data for your property. These reports show events and usage from the
  // last 30 minutes.
  rpc RunRealtimeReport(RunRealtimeReportRequest) returns (RunRealtimeReportResponse) {
    option (google.api.http) = {
      post: "/v1alpha/{property=properties/*}:runRealtimeReport"
      body: "*"
    };
  }
}

// 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 property whose events are tracked. Within a batch request, this entity
  // should either be unspecified or consistent with the batch-level entity.
  Entity entity = 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;

  // The row count of the start row. The first row is counted as row 0.
  //
  // To learn more about this pagination parameter, see
  // [Pagination](https://developers.google.com/analytics/devguides/reporting/data/v1/basics#pagination).
  int64 offset = 5;

  // The number of rows to return. If unspecified, 10 rows are returned. If
  // -1, all rows are returned.
  //
  // To learn more about this pagination parameter, see
  // [Pagination](https://developers.google.com/analytics/devguides/reporting/data/v1/basics#pagination).
  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;

  // 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 = 8;

  // 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 = 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 entity'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 = 11;

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

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

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

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

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

  // The total number of rows in the query result, regardless of the number of
  // rows returned in the response. For example if a query returns 175 rows and
  // includes limit = 50 in the API request, the response will contain row_count
  // = 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 = 12;

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

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

// The request to generate a pivot report.
message RunPivotReportRequest {
  // A property whose events are tracked. Within a batch request, this entity
  // should either be unspecified or consistent with the batch-level entity.
  Entity entity = 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 filter clause of dimensions. Dimensions must be requested to be used in
  // this filter. 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. Metrics must be requested to be used in this filter.
  // Dimensions cannot be used in this filter.
  FilterExpression metric_filter = 5;

  // 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 = 6;

  // 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 = 7;

  // A currency code in ISO4217 format, such as "AED", "USD", "JPY".
  // If the field is empty, the report uses the entity'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 = 7;

  // 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;

  // 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 = 4;

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

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

// The batch request containing multiple report requests.
message BatchRunReportsRequest {
  // A property whose events are tracked. This entity must be specified for the
  // batch. The entity within RunReportRequest may either be unspecified or
  // consistent with this entity.
  Entity entity = 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;
}

// The batch request containing multiple pivot report requests.
message BatchRunPivotReportsRequest {
  // A property whose events are tracked. This entity must be specified for the
  // batch. The entity within RunPivotReportRequest may either be unspecified or
  // consistent with this entity.
  Entity entity = 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;
}

// 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 number of rows to return. If unspecified, 10 rows are returned. If
  // -1, all rows are returned.
  int64 limit = 4;

  // 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 = 5;

  // 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 = 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 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, regardless of the number of
  // rows returned in the response. For example if a query returns 175 rows and
  // includes limit = 50 in the API request, the response will contain row_count
  // = 175 but only 50 rows.
  int32 row_count = 7;

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