Core Reporting API - 參考指南

本文件提供 Core Reporting API 3.0 版查詢和回應的完整參考資料。

簡介

您將透過 Core Reporting API 查詢 Google Analytics (分析) 報表資料。每項查詢都需要有資料檢視 (設定檔) ID、開始和結束日期，以及至少一項指標。您也可以提供其他查詢參數，例如維度、篩選器和區隔，藉此縮小查詢範圍。請參閱 總覽指南，瞭解這些概念如何搭配運作。

要求

API 提供單一要求資料的方法：

analytics.data.ga.get()

此方法會在不同的用戶端程式庫中公開，且具備語言專屬介面，可用來設定查詢參數。

此 API 也可做為符合 REST 樣式的端點進行查詢：

Authorization: Bearer {oauth2-token}

GET https://www.googleapis.com/analytics/v3/data/ga
  ?ids=ga:12345
  &start-date=2008-10-01
  &end-date=2008-10-31
  &metrics=ga:sessions,ga:bounces

每個網址查詢參數都指定一個必須進行網址編碼的 API 查詢參數。

查詢參數摘要

下表摘要列出 Core Reporting API 接受的所有查詢參數。按一下各參數名稱即可查看詳細說明。

名稱 值 必要 摘要
ids string 是 表單「ga:XXXX」的專屬資料表 ID，其中 XXXX 是查詢擷取資料的 Analytics (分析) 資料檢視 (設定檔) ID。
start-date string 是 擷取 Analytics (分析) 資料的開始日期。要求可以指定採用 YYYY-MM-DD 格式的開始日期，或以相對日期的形式指定 (例如today、yesterday 或 NdaysAgo，其中 N 為正整數)。
end-date string 是 擷取 Analytics (分析) 資料的結束日期。要求可以指定採用 YYYY-MM-DD 格式的結束日期或相對日期 (例如today、yesterday 或 NdaysAgo，其中 N 為正整數)。
metrics string 是 以半形逗號分隔的指標清單，例如 ga:sessions,ga:bounces。
dimensions string 否 Analytics (分析) 資料維度清單 (以半形逗號分隔)，例如 ga:browser,ga:city。
sort string 否 以半形逗號分隔的維度和指標清單，指出傳回資料的排序順序和排序方向。
filters string 否 維度或指標篩選器，用於限制要求傳回的資料。
segment string 否 區隔要求傳回的資料。
samplingLevel string 否 所需的取樣層級。允許的值：
  • DEFAULT：傳回樣本大小的回應，在速度和準確率之間取得平衡。
  • FASTER：傳回樣本大小較小的快速回應。
  • HIGHER_PRECISION：使用大型樣本大小傳回更準確的回應，但這可能會導致回應速度變慢。
include-empty-rows boolean 否 預設值為 true；如果設為 False，回應會略過所有指標值為零的資料列。
start-index integer 否 要擷取的第一列資料，從 1 開始。請用這個參數做為分頁機制和 max-results 參數。
max-results integer 否 要納入回應的資料列數量上限。
output string 否 回應中傳回的 Analytics (分析) 資料所需的輸出類型。 可接受的值為 json 和 dataTable。預設值：json。
fields string 否 選取器，用於指定要包含在回應中的欄位子集。
prettyPrint string 否 傳回包含縮排和分行的回應。預設 false。
userIp string 否 指定發出 API 呼叫的使用者 IP 位址。 用於每個 IP 的用量上限。
quotaUser string 否 如果使用者 IP 位址不明，則為 userIp 的替代項目。
access_token string 否 提供 OAuth 2.0 權杖的其中一種方式。
callback string 否 處理回應的 JavaScript 回呼函式名稱。用於 JavaScript JSON-P 要求。
key string 否 用於 OAuth 1.0a 授權，用於指定取得配額的應用程式。例如：key=AldefliuhSFADSfasdfasdfASdf。

查詢參數詳細資料

ids

ids=ga:12345
這是必填欄位。
用來擷取 Analytics (分析) 資料的專屬 ID。這個 ID 是命名空間 ga: 與 Analytics (分析) 資料檢視 (設定檔) ID 的串連。您可以使用 analytics.management.profiles.list 方法擷取資料檢視 (設定檔) ID，以便在 Google Analytics Management API 的檢視畫面 (設定檔) 資源中提供 id。

開始日期

start-date=2009-04-20
這是必填欄位。
所有 Analytics (分析) 資料要求都必須指定日期範圍。 如果您未在要求中加入 start-date 和 end-date 參數，伺服器會傳回錯誤。您可以使用模式 YYYY-MM-DD 或 today、yesterday 或 NdaysAgo 模式，指定特定日期的日期值。值必須與 [0-9]{4}-[0-9]{2}-[0-9]{2}|today|yesterday|[0-9]+(daysAgo) 相符。
最早有效的 start-date 為 2005-01-01。 開始日期沒有上限。
相對日期一律會以查詢時的目前日期為準，以查詢中指定的資料檢視 (設定檔) 為準。

使用相對日期最近 7 天 (從昨天開始) 的日期範圍範例：

  &start-date=7daysAgo
  &end-date=yesterday

結束日期

end-date=2009-05-20
這是必填欄位。
所有 Analytics (分析) 資料要求都必須指定日期範圍。 如果您未在要求中加入 start-date 和 end-date 參數，伺服器會傳回錯誤。您可以使用模式 YYYY-MM-DD 或 today、yesterday 或 NdaysAgo 模式，指定特定日期的日期值。值必須與 [0-9]{4}-[0-9]{2}-[0-9]{2}|today|yesterday|[0-9]+(daysAgo) 相符。
最早有效的 end-date 為 2005-01-01。end-date 沒有上限。
相對日期一律會以查詢時的目前日期為準，以查詢中指定的資料檢視 (設定檔) 為準。

最近 10 天 (從今天開始) 的日期範圍範例：

  &start-date=9daysAgo
  &end-date=today

尺寸

dimensions=ga:browser,ga:city
選用。
dimensions 參數會按照常見條件細分指標，例如 ga:browser 或 ga:city。雖然您可以要求取得網站的總瀏覽量，但最好還是要求提供按瀏覽器細分的瀏覽量資料。在此情況下，您會看到來自 Firefox、Internet Explorer、Chrome 等的網頁瀏覽次數。

在資料要求中使用 dimensions 時，請注意下列限制：

  • 每個查詢最多可提供 7 個維度。
  • 您無法傳送僅由維度組成的查詢，您必須為任何要求的維度結合至少一項指標。
  • 同一項查詢只能查詢特定維度。請使用 維度和指標參考資料中的有效組合工具，查看哪些維度可搭配使用。

metrics

metrics=ga:sessions,ga:bounces
這是必填欄位。
網站使用者活動的匯總統計資料，例如點擊次數或網頁瀏覽量。 如果查詢沒有 dimensions 參數，傳回的指標會針對要求的日期範圍提供匯總值，例如整體網頁瀏覽或總跳出次數。但是，收到維度要求時，系統會按維度值區隔值。舉例來說，如果使用 ga:country 要求 ga:pageviews，系統會傳回每個國家/地區的總網頁瀏覽量。要求取得指標時，請注意以下幾點：
  • 每個要求都必須提供至少一個指標；要求不能僅包含維度。
  • 每個查詢最多可提供 10 個指標。
  • 如未指定維度，多個類別的指標組合都可以搭配使用。
  • 指標可以與其他維度或指標搭配使用，但僅限於該指標適用的有效組合。 詳情請參閱維度和指標參考資料。

排序

sort=ga:country,ga:browser
選用。

指標和維度清單，表示傳回資料的排序順序和排序方向。

  • 系統會依據所列出的指標和維度由左至右的順序指定「排序」。
  • 「方向」direction排序預設為遞增，只要在要求欄位中加上減號 (-) 前置字串，即可變更為遞減。

將查詢結果排序，您就能針對資料提出不同的問題。舉例來說，如要解決「我最常使用哪些國家/地區？他們最常使用哪些瀏覽器？」這類問題，你可以使用下列參數執行查詢。其先按 ga:country 再按 ga:browser 排序，兩者皆以遞增順序排序：

sort=ga:country,ga:browser

如要回答「我最常使用哪些瀏覽器，以及哪些國家/地區最常使用？」這類問題，您可以使用下列參數執行查詢。這會先依 ga:browser 再按 ga:country 排序，兩者皆以遞增順序排序：
sort=ga:browser,ga:country

使用 sort 參數時，請注意下列事項：

  • 請僅依據您在 dimensions 或 metrics 參數中使用的維度或指標值排序。如果要求排序的欄位沒有在維度或指標參數中指出，您就會收到錯誤訊息。
  • 根據預設，字串會按照 en-US 語言代碼的字母順序遞增排序。
  • 根據預設，數字會按遞增編號排序。
  • 根據預設，日期會按照日期遞增排序。

篩選器

filters=ga:medium%3D%3Dreferral
  1. 篩選器語法
  2. 篩選器運算子
  3. 篩選器運算式
  4. 合併篩選器
選用。

filters 查詢字串參數會限制要求傳回的資料。如要使用 filters 參數，請提供要篩選的維度或指標，並在後面加上篩選器運算式。舉例來說，下列查詢要求檢視畫面 (設定檔) 12134 的 ga:pageviews 和 ga:browser，其中 ga:browser 維度的開頭為 Firefox 字串：

https://www.googleapis.com/analytics/v3/data/ga
?ids=ga:12134
&dimensions=ga:browser
&metrics=ga:pageviews
&filters=ga:browser%3D~%5EFirefox
&start-date=2007-01-01
&end-date=2007-12-31

查詢經過篩選，會限制能夠 (或未) 納入結果的資料列。結果中的每一列都會經過篩選器的測試：如果篩選器達成比對，系統會保留該列，比對不相符就捨棄該資料列。

  • 網址編碼：Google API 用戶端程式庫會自動為篩選器運算子進行編碼。
  • 維度篩選：篩選是在任何維度匯總「之前」進行的，因此傳回的指標只代表相關維度的總數。在上述範例中，網頁瀏覽量只包括在 Firefox 中做為瀏覽器的網頁瀏覽量。
  • 指標篩選：在指標匯總「之後」，系統才會篩選指標。
  • 有效組合：您可以篩選不屬於查詢的維度或指標，前提是要求中「而且」篩選器是有效組合。例如，您可能想要查詢特定日期的網頁瀏覽清單，並篩選特定瀏覽器。詳情請參閱維度和指標參考資料。

篩選器語法


單一篩選器的形式如下：

ga:name operator expression

在這個語法中：

  • name：做為篩選依據的維度或指標名稱。例如：ga:pageviews 篩選網頁瀏覽量指標。
  • operator — 定義要使用的篩選器比對類型。運算子專用於維度或指標。
  • expression - 指出結果中要包含或排除的值。運算式使用規則運算式語法。

篩選器運算子


維度有六種篩選運算子和六個篩選器運算子。運算子必須經過網址編碼才能納入網址查詢字串中。

提示：請使用資料動態饋給查詢探索工具設計需要網址編碼的篩選器，因為 Query Explorer 會自動為包含字串和空格的網址編碼。

指標篩選器
運算子 說明 網址編碼格式 示例
== 等於 %3D%3D 傳回網頁時間完全符合 10 秒的結果：
filters=ga:timeOnPage%3D%3D10
!= 不等於 !%3D 傳回網頁停留時間「不是」10 秒的結果：
filters=ga:timeOnPage!%3D10
> 大於 %3E 傳回網頁時間大於 10 秒的結果：
filters=ga:timeOnPage%3E10
< 小於 %3C 傳回網頁時間小於 10 秒的結果：
filters=ga:timeOnPage%3C10
>= 大於或等於 %3E%3D 傳回網頁停留時間至少為 10 秒的結果：
filters=ga:timeOnPage%3E%3D10
<= 小於或等於 %3C%3D 傳回網頁停留時間在 10 秒以內的結果：
filters=ga:timeOnPage%3C%3D10

維度篩選器
運算子 說明 網址編碼格式 範例
== 完全比對 %3D%3D 匯總城市為 Irvine 的指標：
filters=ga:city%3D%3DIrvine
!= 不相符 !%3D 匯總城市並非 爾灣的指標：
filters=ga:city!%3DIrvine
=@ 包含子字串 %3D@ 匯總城市包含約克的指標：
filters=ga:city%3D@York
!@ 不含子字串 !@ 匯總不含約克的城市指標：
filters=ga:city!@York
=~ 與規則運算式相符 %3D~ 匯總城市以「New」開頭的指標：
filters=ga:city%3D~%5ENew.*
(%5E 是從 ^ 字元編碼的網址，固定字串的開頭有模式)。
!~ 不符合規則運算式 !~ 匯總城市名稱開頭以外的值：
filters=ga:city!~%5ENew.*

篩選器運算式

篩選運算式有幾個重要規則：

  • 網址保留字元 — & 等字元必須以正常的方式進行網址編碼。
  • 保留字元 — 當分號和逗號出現在運算式時，必須以反斜線逸出：
    • 分號 \;
    • 逗號 \,
  • 規則運算式：您也可以透過 =~ 和 !~ 運算子，在篩選運算式中使用規則運算式。這類運算子的語法和 Perl 規則運算式類似，並且有以下額外規則：
    • 長度上限為 128 個字元：如果規則運算式長度超過 128 個字元，伺服器會傳回 400 Bad Request 狀態碼。
    • 區分大小寫 - 規則運算式比對不區分大小寫。

合併篩選器

篩選器可使用 OR 和 AND 布林邏輯合併。這樣一來，您就能有效延長篩選運算式 128 個字元的上限。

OR

OR 運算子是以半形逗號 (,) 定義。 其優先順序高於 AND 運算子，且「不得」用於在同一個運算式中合併維度和指標。

範例： (每個都必須進行網址編碼)

國家/地區為 (美國或加拿大)：
ga:country==United%20States,ga:country==Canada

Firefox 使用者 (Windows 或 Macintosh) 作業系統的使用者：
ga:browser==Firefox;ga:operatingSystem==Windows,ga:operatingSystem==Macintosh

AND

AND 運算子是以分號 (;) 開頭。 前方有 OR 運算子，而 CAN 可用來在同一個運算式中合併維度和指標。

範例： (每個都必須進行網址編碼)

國家/地區為美國，且瀏覽器為 Firefox：
ga:country==United%20States;ga:browser==Firefox

國家/地區為美國，且語言開頭不是「en」：
ga:country==United%20States;ga:language!~^en.*

作業系統為 (Windows 或 Macintosh)「且」瀏覽器為 (Firefox 或 Chrome)：
ga:operatingSystem==Windows,ga:operatingSystem==Macintosh;ga:browser==Firefox,ga:browser==Chrome

國家/地區為美國「且」工作階段大於 5：
ga:country==United%20States;ga:sessions>5


區隔

segment=gaid::-10
segment=sessions::condition::ga:medium%3D%3Dreferral
segment=users::condition::ga:browser%3D%3DChrome
選用。

如需如何在 Core Reporting API 中要求區隔的完整詳細資料，請參閱區隔開發指南。

如需區隔的概念總覽，請參閱說明中心的「區隔功能參考資料」和「 區隔」說明文章。

區隔中允許的維度和指標。
只有部分維度和指標可用於區隔。如要查看區隔中可使用的維度和指標，請前往 Dimensions and Metrics Explorer。

samplingLevel

samplingLevel=DEFAULT
選用。
使用這個參數為報表查詢設定取樣層級 (例如用來計算結果的工作階段數)。可以使用的值與網頁介面一致，包括：
  • DEFAULT：傳回樣本大小的回應，在速度和準確率之間取得平衡。
  • FASTER：傳回樣本大小較小的快速回應。
  • HIGHER_PRECISION：使用大型樣本大小傳回更準確的回應，但這可能會導致回應速度變慢。
如未提供，系統會使用 DEFAULT 的取樣等級。
請參閱「取樣」一節，進一步瞭解如何計算用於查詢的工作階段百分比。

包含空白資料列

include-empty-rows=true
選用。
預設為 true；如果設為 False，回應中會忽略所有指標值為零的資料列。舉例來說，如果您在查詢中加入多個指標，則只有在所有指標值都是零的情況下，才會移除資料列。當系統提出要求時，如果有效資料列的數量預期會大幅小到預期維度值數量，這項功能就很實用。

起始索引

start-index=10
選用。
如未提供，則起始索引為 1。(結果索引是從 1 開始)。也就是說，第一列是第 1 列，而不是第 0 列。如果 totalResults 超過 10,000，而您想擷取索引在 10,001 之後的資料列，請使用這個參數做為分頁機制和 max-results 參數。

max-results

max-results=100
選用。
此回應內含的資料列數量上限。您可以將這個方法與 start-index 搭配使用來擷取元素子集，也可以單獨使用，藉此限制傳回的元素數量 (從第一個元素開始)。如未提供 max-results，查詢會傳回預設最多 1000 個資料列。
無論您要求多少資料，Analytics (分析) Core Reporting API 都能傳回最多 10,000 個資料列。如果維度區隔數量未達預期，系統也會傳回比要求少的資料列。舉例來說，ga:country 的可能值少於 300 個，因此，如果只依國家/地區區隔資料，即使將 max-results 設為較高的值，也最多只能產生 300 列資料。

output

output=dataTable
選用。
使用這個參數，即可設定回應中傳回的 Analytics (分析) 資料的輸出類型。允許的值如下：
  • json：在回應中輸出預設 rows 屬性，其中包含 JSON 物件。
  • dataTable：在回應中輸出 dataTable 屬性，其中包含 資料表物件。這個 Data Table 物件可以直接與 Google Charts 圖表搭配使用。
如未提供，系統會使用預設的 JSON 回應。

欄位

fields=rows,columnHeaders(name,dataType)
選用。

指定要在部分回應中傳回的欄位。如果您只會在 API 回應中使用部分欄位，可以使用 fields 參數指定要包含的欄位。

欄位要求參數值的格式約略以 XPath 語法為基礎。支援的語法摘要如下。

  • 使用以逗號分隔的清單來選取多個欄位。
  • 使用 a/b 選取巢狀於欄位 a 中的欄位 b；使用 a/b/c 選取巢狀結構中的 b 欄位 c。
  • 透過在括號 "( )" 中放入運算式，使用子選取器來要求一組指定的陣列或物件子欄位。
    例如：fields=columnHeaders(name,dataType) 只會傳回 columnHeaders 陣列中的 name 和 dataType 欄位。您也可以指定單一子欄位，其中 fields=columnHeader(name) 等於 fields=columnHeader/name。

prettyPrint

prettyPrint=false
選用。

如果為 true，則以使用者可理解的格式傳回回應。 預設值為 false。

quotaUser

quotaUser=4kh4r2h4
選用。

讓您在使用者 IP 位址不明的情況下，也能透過伺服器端的應用程式 強制執行每個使用者的配額。舉例來說，如果應用程式代表使用者在 App Engine 上執行 Cron 工作，就可能會發生這種情況。您可以選擇專門用來識別使用者的任意字串，但上限為 40 個字元。

如果兩者都提供，就會覆寫 userIp。

回應

如果成功，這項要求就會傳回如下定義的 JSON 結構的回應主體。如果將 output 參數設為 dataTable，要求會傳回具有以下定義的 JSON (資料表) 結構的回應主體。

注意事項：「結果」一詞是指符合查詢的整組資料列，而「回應」則是指目前結果頁面上傳回的一組資料列。如果結果總數大於目前回應的頁面大小，則結果可能會有所不同，詳情請參閱 itemsPerPage 頁面。

JSON
{
  "kind": "analytics#gaData",
  "id": string,
  "selfLink": string,
  "containsSampledData": boolean,
  "query": {
    "start-date": string,
    "end-date": string,
    "ids": string,
    "dimensions": [
      string
    ],
    "metrics": [
      string
    ],
    "include-empty-rows": boolean
    "samplingLevel": string,
    "sort": [
      string
    ],
    "filters": string,
    "segment": string,
    "start-index": integer,
    "max-results": integer
  },
  "itemsPerPage": integer,
  "totalResults": integer,
  "previousLink": string,
  "nextLink": string,
  "profileInfo": {
    "profileId": string,
    "accountId": string,
    "webPropertyId": string,
    "internalWebPropertyId": string,
    "profileName": string,
    "tableId": string
  },
  "columnHeaders": [
    {
      "name": string,
      "columnType": string,
      "dataType": string
    }
  ],
  "rows": [
    [
      string
    ]
  ],
  "sampleSize": string,
  "sampleSpace": string,
  "totalsForAllResults": [
    {
      metricName: string,
      ...
    }
  ]
}

回應欄位

回應主體結構的屬性定義如下：

資源名稱 值 說明
kind string 資源類型。值為「analytics#gaData」。
id string 此資料回應的 ID。
query object 這個物件包含以參數形式傳送至查詢的所有值。每個欄位的意義都有對應查詢參數的說明。
query.start-date string 開始日期。
query.end-date string 結束日期。
query.ids string 不重複的資料表 ID。
query.dimensions[] list 數據分析維度清單。
query.metrics[] list 數據分析指標清單。
query.samplingLevel string Requested sampling level.
query.include-empty-rows boolean 預設值為 true；如果設為 False，回應會略過所有指標值皆為零的資料列。
query.sort[] list 資料排序依據的指標或維度清單。
query.filters string 以半形逗號分隔的指標或維度篩選器清單。
query.segment string Analytics (分析) 區隔。
query.start-index integer 開始索引。
query.max-results integer 每頁結果數量上限。
startIndex integer start-index 查詢參數指定資料列的起始索引。預設值為 1。
itemsPerPage integer 回應可包含的資料列數量上限，無論傳回的實際資料列數為何。如果指定 max-results 查詢參數，則 itemsPerPage 的值會是 max-results 或 10,000 的較小值。itemsPerPage 的預設值為 1000。
totalResults integer 查詢結果中的資料列總數，無論回應中傳回的資料列數為何。如果查詢會產生大量資料列，totalResults 可以大於 itemsPerPage。如要進一步瞭解大型查詢的 totalResults 和 itemsPerPage，請參閱 Paging。
startDate string 資料查詢的開始日期，如 start-date 參數所指定。
endDate string 資料查詢的結束日期，由 end-date 參數指定。
profileInfo object 要求取得資料的資料檢視 (設定檔) 的相關資訊。您可以透過 Google Analytics Management API 取得資料檢視 (設定檔) 資料。
profileInfo.profileId string 資料檢視 (設定檔) ID，例如 1174。
profileInfo.accountId string 這個資料檢視 (設定檔) 所屬的帳戶 ID，例如 30481。
profileInfo.webPropertyId string 此資料檢視 (設定檔) 所屬的網站資源 ID，例如 UA-30481-1。
profileInfo.internalWebPropertyId string 這個資料檢視 (設定檔) 所屬網站資源的內部編號，例如 UA-30481-1。
profileInfo.profileName string 資料檢視 (設定檔) 的名稱。
profileInfo.tableId string 資料檢視 (設定檔) 的資料表 ID，由「ga:」組成，後面接上資料檢視 (設定檔) ID。
containsSampledData boolean 如果回應包含取樣資料，則為 True。
sampleSize string 用來計算取樣資料的樣本數。
sampleSpace string 取樣空間總大小。這代表已選取樣本的可用樣本空間總大小。
columnHeaders[] list 列出維度名稱後方的欄標題。維度和指標的順序與透過 metrics 和 dimensions 參數在要求中指定的順序相同。標頭數量是指維度數量 + 指標數量。
columnHeaders[].name string 維度或指標的名稱。
columnHeaders[].columnType string 資料欄類型。「DIMENSION」或「METRIC」。
columnHeaders[].dataType string 資料類型。維度欄標題只有「STRING」做為資料類型。指標欄標題含有指標值的資料類型，例如 INTEGER、PERCENT、TIME、CURRENCY、FLOAT 等。如要瞭解所有可能的資料類型，請參閱 metadata API 回應。
totalsForAllResults object 要求指標的總值，做為指標名稱和值的鍵/值組合。指標總數的順序與要求中指定的指標順序相同。
rows[] list Analytics (分析) 資料列，其中每一列都包含維度值清單，後面接著指標值。維度和指標的順序與要求中指定的順序相同。每個資料列都有 N 個欄位清單，其中 N = 維度數量 + 指標數量。
JSON (資料表)
{
  "kind": "analytics#gaData",
  "id": string,
  "selfLink": string,
  "containsSampledData": boolean,
  "query": {
    "start-date": string,
    "end-date": string,
    "ids": string,
    "dimensions": [
      string
    ],
    "metrics": [
      string
    ],
    "samplingLevel": string,
    "include-empty-rows": boolean,
    "sort": [
      string
    ],
    "filters": string,
    "segment": string,
    "start-index": integer,
    "max-results": integer
  },
  "itemsPerPage": integer,
  "totalResults": integer,
  "previousLink": string,
  "nextLink": string,
  "profileInfo": {
    "profileId": string,
    "accountId": string,
    "webPropertyId": string,
    "internalWebPropertyId": string,
    "profileName": string,
    "tableId": string
  },
  "columnHeaders": [
    {
      "name": string,
      "columnType": string,
      "dataType": string
    }
  ],
  "dataTable": {
    "cols": [
      {
        "id": string,
        "label": string,
        "type": string
      }
    ],
    "rows": [
      {
        "c": [
          {    
            "v": string
          }
        ]
      }   
    ]
  },
  "sampleSize": string,
  "sampleSpace": string,
  "totalsForAllResults": [
    {
      metricName: string,
      ...
    }
  ]
}

回應欄位

回應主體結構的屬性定義如下：

資源名稱 值 說明
kind string 資源類型。值為「analytics#gaData」。
id string 此資料回應的 ID。
query object 這個物件包含以參數形式傳送至查詢的所有值。每個欄位的意義都有對應查詢參數的說明。
query.start-date string 開始日期。
query.end-date string 結束日期。
query.ids string 不重複的資料表 ID。
query.dimensions[] list 數據分析維度清單。
query.metrics[] list 數據分析指標清單。
query.samplingLevel string Requested sampling level.
query.include-empty-rows boolean 預設值為 true；如果設為 False，回應會略過所有指標值皆為零的資料列。
query.sort[] list 資料排序依據的指標或維度清單。
query.filters string 以半形逗號分隔的指標或維度篩選器清單。
query.segment string Analytics (分析) 區隔。
query.start-index integer 開始索引。
query.max-results integer 每頁結果數量上限。
startIndex integer start-index 查詢參數指定資料列的起始索引。預設值為 1。
itemsPerPage integer 回應可包含的資料列數量上限，無論傳回的實際資料列數為何。如果指定 max-results 查詢參數，則 itemsPerPage 的值會是 max-results 或 10,000 的較小值。itemsPerPage 的預設值為 1000。
totalResults integer 查詢結果中的資料列總數，無論回應中傳回的資料列數為何。如果查詢會產生大量資料列，totalResults 可以大於 itemsPerPage。如要進一步瞭解大型查詢的 totalResults 和 itemsPerPage，請參閱 Paging。
startDate string 資料查詢的開始日期，如 start-date 參數所指定。
endDate string 資料查詢的結束日期，由 end-date 參數指定。
profileInfo object 要求取得資料的資料檢視 (設定檔) 的相關資訊。您可以透過 Google Analytics Management API 取得資料檢視 (設定檔) 資料。
profileInfo.profileId string 資料檢視 (設定檔) ID，例如 1174。
profileInfo.accountId string 這個資料檢視 (設定檔) 所屬的帳戶 ID，例如 30481。
profileInfo.webPropertyId string 此資料檢視 (設定檔) 所屬的網站資源 ID，例如 UA-30481-1。
profileInfo.internalWebPropertyId string 這個資料檢視 (設定檔) 所屬網站資源的內部編號，例如 UA-30481-1。
profileInfo.profileName string 資料檢視 (設定檔) 的名稱。
profileInfo.tableId string 資料檢視 (設定檔) 的資料表 ID，由「ga:」組成，後面接上資料檢視 (設定檔) ID。
containsSampledData boolean 如果回應包含取樣資料，則為 True。
sampleSize string 用來計算取樣資料的樣本數。
sampleSpace string 取樣空間總大小。這代表已選取樣本的可用樣本空間總大小。
columnHeaders[] list 列出維度名稱後方的欄標題。維度和指標的順序與透過 metrics 和 dimensions 參數在要求中指定的順序相同。標頭數量是指維度數量 + 指標數量。
columnHeaders[].name string 維度或指標的名稱。
columnHeaders[].columnType string 資料欄類型。「DIMENSION」或「METRIC」。
columnHeaders[].dataType string 資料類型。維度欄標題只有「STRING」做為資料類型。指標欄標題含有指標值的資料類型，例如 INTEGER、PERCENT、TIME、CURRENCY、FLOAT 等。如要瞭解所有可能的資料類型，請參閱 metadata API 回應。
totalsForAllResults object 要求指標的總值，做為指標名稱和值的鍵/值組合。指標總數的順序與要求中指定的指標順序相同。
dataTable object 可與 Google 圖表搭配使用的資料表物件。
dataTable.cols[] list 指標後接指標的資料欄描述元清單。維度和指標的順序與透過 metrics 和 dimensions 參數在要求中指定的順序相同。欄數是維度數量 + 指標數量。
dataTable.cols[].id string ID，可用來參照特定資料欄 (除了使用資料欄索引的替代方案)。維度或指標 ID 可用來設定這個值。
dataTable.cols[].label string 資料欄的標籤 (可能會顯示於圖表)。維度或指標 ID 可用來設定這個值。
dataTable.cols[].type string 這個資料欄的資料類型。
dataTable.rows[] list 資料表格格式的 Analytics (分析) 資料列，其中每一列都是物件，內含維度和指標的儲存格值清單。維度和指標的順序與要求中指定的順序相同。每個儲存格都有一個 N 欄位清單，其中 N = 維度數量 + 指標數量。

錯誤代碼

如果要求成功，Core Reporting API 會傳回 200 HTTP 狀態碼。如果處理查詢時發生錯誤，API 會傳回錯誤代碼和說明。每個使用 Analytics API 的應用程式都必須導入適當的錯誤處理邏輯。如要進一步瞭解錯誤代碼及其處理方式，請參閱 錯誤回應參考指南。

歡迎試用！

您可以嘗試透過 Core Reporting API 執行查詢。

  • 如要在查詢中查看有效的指標和維度組合，請在查詢探索工具中輸入參數的範例值。範例查詢結果會以資料表形式顯示，內含所有指定指標和維度的值。

  • 如要對即時資料提出要求，並查看 JSON 格式的回應，請嘗試在 Google Data APIs Explorer 中使用 analytics.data.ga.get 方法。

取樣

Google Analytics (分析) 會即時計算特定維度和指標的組合。為了在合理的時間內傳回資料，Google Analytics (分析) 可能只會處理資料樣本。

您可以設定 samplingLevel 參數，指定要求的取樣等級。

如果 Core Reporting API 回應包含取樣資料，則 containsSampledData 回應欄位為 true。此外，有 2 項屬性將提供查詢的取樣層級相關資訊：sampleSize 和 sampleSpace。您可以利用這 2 個值，計算用於查詢的工作階段百分比。舉例來說，如果 sampleSize 是 201,000 而 sampleSpace 是 220,000，則報表會以 (201,000 / 220,000) * 100 = 91.36% 的工作階段為依據。

如需取樣的一般說明及在 Google Analytics (分析) 中的使用方式，請參閱取樣一文。


處理大型資料結果

如果您預期查詢會傳回大型結果集，請參考下方指南協助您最佳化 API 查詢、避免錯誤，並將配額超額降到最低。請注意，為了設定效能基準，每個 API 要求最多可允許 7 個維度和 10 個指標。雖然某些指定大量指標和維度的查詢可能需要較長的處理時間，但限制要求的指標數量可能不足以改善查詢效能。建議您改用下列技巧，獲得最佳效能結果。

減少每次查詢的維度

API 可讓您在任何請求中指定最多 7 個維度。 很多時候，Google Analytics (分析) 必須即時計算這些複雜查詢結果。如果產生的資料列數量偏高，可能相當耗時。舉例來說，按城市 (按城市劃分) 查詢關鍵字，可能會符合數百萬列的資料。您可以限制查詢中的維度數量，減少 Google Analytics (分析) 需要處理的資料列數量，藉此提升效能。

按日期範圍拆分查詢

請考慮一次處理一週 (甚至是一天) 的個別查詢，而不是逐頁瀏覽某個較長的日期範圍 (以日期表示) 的結果。當然，對於大型資料集，即使要求的是一天資料，系統也可能傳回超過 max-results，這時無法避免分頁。但在任何情況下，如果查詢的相符資料列數高於 max-results，則分隔日期範圍可能會減少擷取結果的總時間。這個方法可以改善單一執行緒和平行查詢的效能。

Paging

逐頁瀏覽結果是將大型結果集分成多個可管理區塊的實用方法。totalResults 欄位會顯示相符的資料列數量，itemsPerPage 則提供結果中可獲得的資料列數量上限。如果 totalResults 到 itemsPerPage 的比例很高，則個別查詢的處理時間可能會超過必要。如果您只需要少量的資料列 (例如為了顯示用途)，透過 max-results 參數設定明確的回應大小限制會比較方便。不過，如果您的應用程式需要處理大量的大量結果，則要求允許的資料列數量上限可能更有效率。

使用 gzip

如果想要減少每個要求所需的頻寬，最簡單的方法就是啟用 gzip 壓縮。雖然此方法需要額外的 CPU 時間解壓縮結果，但相對可省下網路費用。如要接收以 gzip 編碼的回應，您必須執行下列兩項操作：設定 Accept-Encoding 標頭，並修改使用者代理程式來加入 gzip 字串。以下是啟用 gzip 壓縮的正確 HTTP 標頭格式範例：

Accept-Encoding: gzip
User-Agent: my program (gzip)