analytics_data_api.proto 22 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554
  1. // Copyright 2021 Google LLC
  2. //
  3. // Licensed under the Apache License, Version 2.0 (the "License");
  4. // you may not use this file except in compliance with the License.
  5. // You may obtain a copy of the License at
  6. //
  7. // http://www.apache.org/licenses/LICENSE-2.0
  8. //
  9. // Unless required by applicable law or agreed to in writing, software
  10. // distributed under the License is distributed on an "AS IS" BASIS,
  11. // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12. // See the License for the specific language governing permissions and
  13. // limitations under the License.
  14. syntax = "proto3";
  15. package google.analytics.data.v1beta;
  16. import "google/analytics/data/v1beta/data.proto";
  17. import "google/api/annotations.proto";
  18. import "google/api/client.proto";
  19. import "google/api/field_behavior.proto";
  20. import "google/api/resource.proto";
  21. option go_package = "google.golang.org/genproto/googleapis/analytics/data/v1beta;data";
  22. option java_multiple_files = true;
  23. option java_outer_classname = "AnalyticsDataApiProto";
  24. option java_package = "com.google.analytics.data.v1beta";
  25. // Google Analytics reporting data service.
  26. service BetaAnalyticsData {
  27. option (google.api.default_host) = "analyticsdata.googleapis.com";
  28. option (google.api.oauth_scopes) =
  29. "https://www.googleapis.com/auth/analytics,"
  30. "https://www.googleapis.com/auth/analytics.readonly";
  31. // Returns a customized report of your Google Analytics event data. Reports
  32. // contain statistics derived from data collected by the Google Analytics
  33. // tracking code. The data returned from the API is as a table with columns
  34. // for the requested dimensions and metrics. Metrics are individual
  35. // measurements of user activity on your property, such as active users or
  36. // event count. Dimensions break down metrics across some common criteria,
  37. // such as country or event name.
  38. rpc RunReport(RunReportRequest) returns (RunReportResponse) {
  39. option (google.api.http) = {
  40. post: "/v1beta/{property=properties/*}:runReport"
  41. body: "*"
  42. };
  43. }
  44. // Returns a customized pivot report of your Google Analytics event data.
  45. // Pivot reports are more advanced and expressive formats than regular
  46. // reports. In a pivot report, dimensions are only visible if they are
  47. // included in a pivot. Multiple pivots can be specified to further dissect
  48. // your data.
  49. rpc RunPivotReport(RunPivotReportRequest) returns (RunPivotReportResponse) {
  50. option (google.api.http) = {
  51. post: "/v1beta/{property=properties/*}:runPivotReport"
  52. body: "*"
  53. };
  54. }
  55. // Returns multiple reports in a batch. All reports must be for the same
  56. // GA4 Property.
  57. rpc BatchRunReports(BatchRunReportsRequest) returns (BatchRunReportsResponse) {
  58. option (google.api.http) = {
  59. post: "/v1beta/{property=properties/*}:batchRunReports"
  60. body: "*"
  61. };
  62. }
  63. // Returns multiple pivot reports in a batch. All reports must be for the same
  64. // GA4 Property.
  65. rpc BatchRunPivotReports(BatchRunPivotReportsRequest) returns (BatchRunPivotReportsResponse) {
  66. option (google.api.http) = {
  67. post: "/v1beta/{property=properties/*}:batchRunPivotReports"
  68. body: "*"
  69. };
  70. }
  71. // Returns metadata for dimensions and metrics available in reporting methods.
  72. // Used to explore the dimensions and metrics. In this method, a Google
  73. // Analytics GA4 Property Identifier is specified in the request, and
  74. // the metadata response includes Custom dimensions and metrics as well as
  75. // Universal metadata.
  76. //
  77. // For example if a custom metric with parameter name `levels_unlocked` is
  78. // registered to a property, the Metadata response will contain
  79. // `customEvent:levels_unlocked`. Universal metadata are dimensions and
  80. // metrics applicable to any property such as `country` and `totalUsers`.
  81. rpc GetMetadata(GetMetadataRequest) returns (Metadata) {
  82. option (google.api.http) = {
  83. get: "/v1beta/{name=properties/*/metadata}"
  84. };
  85. option (google.api.method_signature) = "name";
  86. }
  87. // The Google Analytics Realtime API returns a customized report of realtime
  88. // event data for your property. These reports show events and usage from the
  89. // last 30 minutes.
  90. rpc RunRealtimeReport(RunRealtimeReportRequest) returns (RunRealtimeReportResponse) {
  91. option (google.api.http) = {
  92. post: "/v1beta/{property=properties/*}:runRealtimeReport"
  93. body: "*"
  94. };
  95. }
  96. }
  97. // The dimensions and metrics currently accepted in reporting methods.
  98. message Metadata {
  99. option (google.api.resource) = {
  100. type: "analyticsdata.googleapis.com/Metadata"
  101. pattern: "properties/{property}/metadata"
  102. };
  103. // Resource name of this metadata.
  104. string name = 3;
  105. // The dimension descriptions.
  106. repeated DimensionMetadata dimensions = 1;
  107. // The metric descriptions.
  108. repeated MetricMetadata metrics = 2;
  109. }
  110. // The request to generate a report.
  111. message RunReportRequest {
  112. // A Google Analytics GA4 property identifier whose events are tracked.
  113. // Specified in the URL path and not the body. To learn more, see [where to
  114. // find your Property
  115. // ID](https://developers.google.com/analytics/devguides/reporting/data/v1/property-id).
  116. // Within a batch request, this property should either be unspecified or
  117. // consistent with the batch-level property.
  118. //
  119. // Example: properties/1234
  120. string property = 1;
  121. // The dimensions requested and displayed.
  122. repeated Dimension dimensions = 2;
  123. // The metrics requested and displayed.
  124. repeated Metric metrics = 3;
  125. // Date ranges of data to read. If multiple date ranges are requested, each
  126. // response row will contain a zero based date range index. If two date
  127. // ranges overlap, the event data for the overlapping days is included in the
  128. // response rows for both date ranges. In a cohort request, this `dateRanges`
  129. // must be unspecified.
  130. repeated DateRange date_ranges = 4;
  131. // The filter clause of dimensions. Dimensions must be requested to be used in
  132. // this filter. Metrics cannot be used in this filter.
  133. FilterExpression dimension_filter = 5;
  134. // The filter clause of metrics. Applied at post aggregation phase, similar to
  135. // SQL having-clause. Metrics must be requested to be used in this filter.
  136. // Dimensions cannot be used in this filter.
  137. FilterExpression metric_filter = 6;
  138. // The row count of the start row. The first row is counted as row 0.
  139. //
  140. // When paging, the first request does not specify offset; or equivalently,
  141. // sets offset to 0; the first request returns the first `limit` of rows. The
  142. // second request sets offset to the `limit` of the first request; the second
  143. // request returns the second `limit` of rows.
  144. //
  145. // To learn more about this pagination parameter, see
  146. // [Pagination](https://developers.google.com/analytics/devguides/reporting/data/v1/basics#pagination).
  147. int64 offset = 7;
  148. // The number of rows to return. If unspecified, 10,000 rows are returned. The
  149. // API returns a maximum of 100,000 rows per request, no matter how many you
  150. // ask for. `limit` must be positive.
  151. //
  152. // The API can also return fewer rows than the requested `limit`, if there
  153. // aren't as many dimension values as the `limit`. For instance, there are
  154. // fewer than 300 possible values for the dimension `country`, so when
  155. // reporting on only `country`, you can't get more than 300 rows, even if you
  156. // set `limit` to a higher value.
  157. //
  158. // To learn more about this pagination parameter, see
  159. // [Pagination](https://developers.google.com/analytics/devguides/reporting/data/v1/basics#pagination).
  160. int64 limit = 8;
  161. // Aggregation of metrics. Aggregated metric values will be shown in rows
  162. // where the dimension_values are set to "RESERVED_(MetricAggregation)".
  163. repeated MetricAggregation metric_aggregations = 9;
  164. // Specifies how rows are ordered in the response.
  165. repeated OrderBy order_bys = 10;
  166. // A currency code in ISO4217 format, such as "AED", "USD", "JPY".
  167. // If the field is empty, the report uses the property's default currency.
  168. string currency_code = 11;
  169. // Cohort group associated with this request. If there is a cohort group
  170. // in the request the 'cohort' dimension must be present.
  171. CohortSpec cohort_spec = 12;
  172. // If false or unspecified, each row with all metrics equal to 0 will not be
  173. // returned. If true, these rows will be returned if they are not separately
  174. // removed by a filter.
  175. bool keep_empty_rows = 13;
  176. // Toggles whether to return the current state of this Analytics Property's
  177. // quota. Quota is returned in [PropertyQuota](#PropertyQuota).
  178. bool return_property_quota = 14;
  179. }
  180. // The response report table corresponding to a request.
  181. message RunReportResponse {
  182. // Describes dimension columns. The number of DimensionHeaders and ordering of
  183. // DimensionHeaders matches the dimensions present in rows.
  184. repeated DimensionHeader dimension_headers = 1;
  185. // Describes metric columns. The number of MetricHeaders and ordering of
  186. // MetricHeaders matches the metrics present in rows.
  187. repeated MetricHeader metric_headers = 2;
  188. // Rows of dimension value combinations and metric values in the report.
  189. repeated Row rows = 3;
  190. // If requested, the totaled values of metrics.
  191. repeated Row totals = 4;
  192. // If requested, the maximum values of metrics.
  193. repeated Row maximums = 5;
  194. // If requested, the minimum values of metrics.
  195. repeated Row minimums = 6;
  196. // The total number of rows in the query result. `rowCount` is independent of
  197. // the number of rows returned in the response, the `limit` request
  198. // parameter, and the `offset` request parameter. For example if a query
  199. // returns 175 rows and includes `limit` of 50 in the API request, the
  200. // response will contain `rowCount` of 175 but only 50 rows.
  201. //
  202. // To learn more about this pagination parameter, see
  203. // [Pagination](https://developers.google.com/analytics/devguides/reporting/data/v1/basics#pagination).
  204. int32 row_count = 7;
  205. // Metadata for the report.
  206. ResponseMetaData metadata = 8;
  207. // This Analytics Property's quota state including this request.
  208. PropertyQuota property_quota = 9;
  209. // Identifies what kind of resource this message is. This `kind` is always the
  210. // fixed string "analyticsData#runReport". Useful to distinguish between
  211. // response types in JSON.
  212. string kind = 10;
  213. }
  214. // The request to generate a pivot report.
  215. message RunPivotReportRequest {
  216. // A Google Analytics GA4 property identifier whose events are tracked.
  217. // Specified in the URL path and not the body. To learn more, see [where to
  218. // find your Property
  219. // ID](https://developers.google.com/analytics/devguides/reporting/data/v1/property-id).
  220. // Within a batch request, this property should either be unspecified or
  221. // consistent with the batch-level property.
  222. //
  223. // Example: properties/1234
  224. string property = 1;
  225. // The dimensions requested. All defined dimensions must be used by one of the
  226. // following: dimension_expression, dimension_filter, pivots, order_bys.
  227. repeated Dimension dimensions = 2;
  228. // The metrics requested, at least one metric needs to be specified. All
  229. // defined metrics must be used by one of the following: metric_expression,
  230. // metric_filter, order_bys.
  231. repeated Metric metrics = 3;
  232. // The date range to retrieve event data for the report. If multiple date
  233. // ranges are specified, event data from each date range is used in the
  234. // report. A special dimension with field name "dateRange" can be included in
  235. // a Pivot's field names; if included, the report compares between date
  236. // ranges. In a cohort request, this `dateRanges` must be unspecified.
  237. repeated DateRange date_ranges = 4;
  238. // Describes the visual format of the report's dimensions in columns or rows.
  239. // The union of the fieldNames (dimension names) in all pivots must be a
  240. // subset of dimension names defined in Dimensions. No two pivots can share a
  241. // dimension. A dimension is only visible if it appears in a pivot.
  242. repeated Pivot pivots = 5;
  243. // The filter clause of dimensions. Dimensions must be requested to be used in
  244. // this filter. Metrics cannot be used in this filter.
  245. FilterExpression dimension_filter = 6;
  246. // The filter clause of metrics. Applied at post aggregation phase, similar to
  247. // SQL having-clause. Metrics must be requested to be used in this filter.
  248. // Dimensions cannot be used in this filter.
  249. FilterExpression metric_filter = 7;
  250. // A currency code in ISO4217 format, such as "AED", "USD", "JPY".
  251. // If the field is empty, the report uses the property's default currency.
  252. string currency_code = 8;
  253. // Cohort group associated with this request. If there is a cohort group
  254. // in the request the 'cohort' dimension must be present.
  255. CohortSpec cohort_spec = 9;
  256. // If false or unspecified, each row with all metrics equal to 0 will not be
  257. // returned. If true, these rows will be returned if they are not separately
  258. // removed by a filter.
  259. bool keep_empty_rows = 10;
  260. // Toggles whether to return the current state of this Analytics Property's
  261. // quota. Quota is returned in [PropertyQuota](#PropertyQuota).
  262. bool return_property_quota = 11;
  263. }
  264. // The response pivot report table corresponding to a pivot request.
  265. message RunPivotReportResponse {
  266. // Summarizes the columns and rows created by a pivot. Each pivot in the
  267. // request produces one header in the response. If we have a request like
  268. // this:
  269. //
  270. // "pivots": [{
  271. // "fieldNames": ["country",
  272. // "city"]
  273. // },
  274. // {
  275. // "fieldNames": "eventName"
  276. // }]
  277. //
  278. // We will have the following `pivotHeaders` in the response:
  279. //
  280. // "pivotHeaders" : [{
  281. // "dimensionHeaders": [{
  282. // "dimensionValues": [
  283. // { "value": "United Kingdom" },
  284. // { "value": "London" }
  285. // ]
  286. // },
  287. // {
  288. // "dimensionValues": [
  289. // { "value": "Japan" },
  290. // { "value": "Osaka" }
  291. // ]
  292. // }]
  293. // },
  294. // {
  295. // "dimensionHeaders": [{
  296. // "dimensionValues": [{ "value": "session_start" }]
  297. // },
  298. // {
  299. // "dimensionValues": [{ "value": "scroll" }]
  300. // }]
  301. // }]
  302. repeated PivotHeader pivot_headers = 1;
  303. // Describes dimension columns. The number of DimensionHeaders and ordering of
  304. // DimensionHeaders matches the dimensions present in rows.
  305. repeated DimensionHeader dimension_headers = 2;
  306. // Describes metric columns. The number of MetricHeaders and ordering of
  307. // MetricHeaders matches the metrics present in rows.
  308. repeated MetricHeader metric_headers = 3;
  309. // Rows of dimension value combinations and metric values in the report.
  310. repeated Row rows = 4;
  311. // Aggregation of metric values. Can be totals, minimums, or maximums. The
  312. // returned aggregations are controlled by the metric_aggregations in the
  313. // pivot. The type of aggregation returned in each row is shown by the
  314. // dimension_values which are set to "RESERVED_<MetricAggregation>".
  315. repeated Row aggregates = 5;
  316. // Metadata for the report.
  317. ResponseMetaData metadata = 6;
  318. // This Analytics Property's quota state including this request.
  319. PropertyQuota property_quota = 7;
  320. // Identifies what kind of resource this message is. This `kind` is always the
  321. // fixed string "analyticsData#runPivotReport". Useful to distinguish between
  322. // response types in JSON.
  323. string kind = 8;
  324. }
  325. // The batch request containing multiple report requests.
  326. message BatchRunReportsRequest {
  327. // A Google Analytics GA4 property identifier whose events are tracked.
  328. // Specified in the URL path and not the body. To learn more, see [where to
  329. // find your Property
  330. // ID](https://developers.google.com/analytics/devguides/reporting/data/v1/property-id).
  331. // This property must be specified for the batch. The property within
  332. // RunReportRequest may either be unspecified or consistent with this
  333. // property.
  334. //
  335. // Example: properties/1234
  336. string property = 1;
  337. // Individual requests. Each request has a separate report response. Each
  338. // batch request is allowed up to 5 requests.
  339. repeated RunReportRequest requests = 2;
  340. }
  341. // The batch response containing multiple reports.
  342. message BatchRunReportsResponse {
  343. // Individual responses. Each response has a separate report request.
  344. repeated RunReportResponse reports = 1;
  345. // Identifies what kind of resource this message is. This `kind` is always the
  346. // fixed string "analyticsData#batchRunReports". Useful to distinguish between
  347. // response types in JSON.
  348. string kind = 2;
  349. }
  350. // The batch request containing multiple pivot report requests.
  351. message BatchRunPivotReportsRequest {
  352. // A Google Analytics GA4 property identifier whose events are tracked.
  353. // Specified in the URL path and not the body. To learn more, see [where to
  354. // find your Property
  355. // ID](https://developers.google.com/analytics/devguides/reporting/data/v1/property-id).
  356. // This property must be specified for the batch. The property within
  357. // RunPivotReportRequest may either be unspecified or consistent with this
  358. // property.
  359. //
  360. // Example: properties/1234
  361. string property = 1;
  362. // Individual requests. Each request has a separate pivot report response.
  363. // Each batch request is allowed up to 5 requests.
  364. repeated RunPivotReportRequest requests = 2;
  365. }
  366. // The batch response containing multiple pivot reports.
  367. message BatchRunPivotReportsResponse {
  368. // Individual responses. Each response has a separate pivot report request.
  369. repeated RunPivotReportResponse pivot_reports = 1;
  370. // Identifies what kind of resource this message is. This `kind` is always the
  371. // fixed string "analyticsData#batchRunPivotReports". Useful to distinguish
  372. // between response types in JSON.
  373. string kind = 2;
  374. }
  375. // Request for a property's dimension and metric metadata.
  376. message GetMetadataRequest {
  377. // Required. The resource name of the metadata to retrieve. This name field is
  378. // specified in the URL path and not URL parameters. Property is a numeric
  379. // Google Analytics GA4 Property identifier. To learn more, see [where to find
  380. // your Property
  381. // ID](https://developers.google.com/analytics/devguides/reporting/data/v1/property-id).
  382. //
  383. // Example: properties/1234/metadata
  384. //
  385. // Set the Property ID to 0 for dimensions and metrics common to all
  386. // properties. In this special mode, this method will not return custom
  387. // dimensions and metrics.
  388. string name = 1 [
  389. (google.api.field_behavior) = REQUIRED,
  390. (google.api.resource_reference) = {
  391. type: "analyticsdata.googleapis.com/Metadata"
  392. }
  393. ];
  394. }
  395. // The request to generate a realtime report.
  396. message RunRealtimeReportRequest {
  397. // A Google Analytics GA4 property identifier whose events are tracked.
  398. // Specified in the URL path and not the body. To learn more, see [where to
  399. // find your Property
  400. // ID](https://developers.google.com/analytics/devguides/reporting/data/v1/property-id).
  401. //
  402. // Example: properties/1234
  403. string property = 1;
  404. // The dimensions requested and displayed.
  405. repeated Dimension dimensions = 2;
  406. // The metrics requested and displayed.
  407. repeated Metric metrics = 3;
  408. // The filter clause of dimensions. Dimensions must be requested to be used in
  409. // this filter. Metrics cannot be used in this filter.
  410. FilterExpression dimension_filter = 4;
  411. // The filter clause of metrics. Applied at post aggregation phase, similar to
  412. // SQL having-clause. Metrics must be requested to be used in this filter.
  413. // Dimensions cannot be used in this filter.
  414. FilterExpression metric_filter = 5;
  415. // The number of rows to return. If unspecified, 10,000 rows are returned. The
  416. // API returns a maximum of 100,000 rows per request, no matter how many you
  417. // ask for. `limit` must be positive.
  418. //
  419. // The API can also return fewer rows than the requested `limit`, if there
  420. // aren't as many dimension values as the `limit`. For instance, there are
  421. // fewer than 300 possible values for the dimension `country`, so when
  422. // reporting on only `country`, you can't get more than 300 rows, even if you
  423. // set `limit` to a higher value.
  424. int64 limit = 6;
  425. // Aggregation of metrics. Aggregated metric values will be shown in rows
  426. // where the dimension_values are set to "RESERVED_(MetricAggregation)".
  427. repeated MetricAggregation metric_aggregations = 7;
  428. // Specifies how rows are ordered in the response.
  429. repeated OrderBy order_bys = 8;
  430. // Toggles whether to return the current state of this Analytics Property's
  431. // Realtime quota. Quota is returned in [PropertyQuota](#PropertyQuota).
  432. bool return_property_quota = 9;
  433. // The minute ranges of event data to read. If unspecified, one minute range
  434. // for the last 30 minutes will be used. If multiple minute ranges are
  435. // requested, each response row will contain a zero based minute range index.
  436. // If two minute ranges overlap, the event data for the overlapping minutes is
  437. // included in the response rows for both minute ranges.
  438. repeated MinuteRange minute_ranges = 10;
  439. }
  440. // The response realtime report table corresponding to a request.
  441. message RunRealtimeReportResponse {
  442. // Describes dimension columns. The number of DimensionHeaders and ordering of
  443. // DimensionHeaders matches the dimensions present in rows.
  444. repeated DimensionHeader dimension_headers = 1;
  445. // Describes metric columns. The number of MetricHeaders and ordering of
  446. // MetricHeaders matches the metrics present in rows.
  447. repeated MetricHeader metric_headers = 2;
  448. // Rows of dimension value combinations and metric values in the report.
  449. repeated Row rows = 3;
  450. // If requested, the totaled values of metrics.
  451. repeated Row totals = 4;
  452. // If requested, the maximum values of metrics.
  453. repeated Row maximums = 5;
  454. // If requested, the minimum values of metrics.
  455. repeated Row minimums = 6;
  456. // The total number of rows in the query result. `rowCount` is independent of
  457. // the number of rows returned in the response and the `limit` request
  458. // parameter. For example if a query returns 175 rows and includes `limit`
  459. // of 50 in the API request, the response will contain `rowCount` of 175 but
  460. // only 50 rows.
  461. int32 row_count = 7;
  462. // This Analytics Property's Realtime quota state including this request.
  463. PropertyQuota property_quota = 8;
  464. // Identifies what kind of resource this message is. This `kind` is always the
  465. // fixed string "analyticsData#runRealtimeReport". Useful to distinguish
  466. // between response types in JSON.
  467. string kind = 9;
  468. }