Core Reporting API - 參考指南

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

簡介

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

要求

API 提供一種要求資料的方法:

analytics.data.ga.get()

此方法會在各種用戶端程式庫中公開,且具有特定語言專用的介面來設定查詢參數。

也可以以 REST 樣式的端點查詢這個 API:

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 或相對日期 (例如todayyesterdayNdaysAgo,其中 N 為正整數。
end-date string Analytics (分析) 資料的擷取結束日期。要求可以指定結束日期,格式為 YYYY-MM-DD 或相對日期 (例如todayyesterdayNdaysAgo,其中 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,則回應中會略過所有指標值為 0 的資料列。
start-index integer 要擷取的第一列資料 (從 1 開始)。請將這個參數當做分頁機制與 max-results 參數搭配使用。
max-results integer 要加進回應的資料列數量上限。
output string 針對回應中傳回的 Analytics (分析) 資料,指定的輸出類型。可接受的值為 jsondataTable。預設值: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-dateend-date 參數,伺服器會傳回錯誤。您可以使用模式 YYYY-MM-DDtodayyesterdayNdaysAgo 模式,指定特定日期的日期值。值必須符合 [0-9]{4}-[0-9]{2}-[0-9]{2}|today|yesterday|[0-9]+(daysAgo)
最早有效的 start-date2005-01-01。 開始日期沒有上限。
相對日期一律以查詢時的目前日期為依據,並以查詢中指定的資料檢視 (設定檔) 時區為準。

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

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

結束日期

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

使用相對日期過去 10 天 (從今天開始) 的日期範圍範例:

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

維度

dimensions=ga:browser,ga:city
選用。
dimensions 參數會根據常見條件細分指標,例如 ga:browserga:city。雖然您可以要求取得網站的網頁瀏覽總數,但您也可以要求取得按瀏覽器細分的網頁瀏覽量資料,或許會更有趣。這時您會看到 Firefox、Internet Explorer、Chrome 等 網頁的網頁瀏覽量。

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

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


metrics

metrics=ga:sessions,ga:bounces
這是必填欄位。
在網站上的使用者活動的匯總統計資料,例如點擊次數或網頁瀏覽。如果查詢沒有 dimensions 參數,傳回的指標會提供指定日期範圍內的匯總值,例如整體網頁瀏覽或跳出總數。不過,在要求維度時,值會依照維度值劃分。舉例來說,如果 ga:pageviews 要求使用 ga:country,系統會傳回每個國家/地區的總網頁瀏覽量。 要求指標時,請注意以下幾點:
  • 任何要求都必須提供至少一項指標,且要求不能只包含維度。
  • 每項查詢最多可提供 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 參數時,請注意下列事項:

  • 依照您在 dimensionsmetrics 參數中使用的維度或指標值排序。如果要求進行排序的欄位未在維度或指標參數中指出,您就會收到錯誤訊息。
  • 根據預設,字串會在 en-US 語言代碼中依字母順序遞增排序。
  • 根據預設,這些數字是依數字順序遞增排序。
  • 根據預設,日期會依照日期遞增排序。

篩選器

filters=ga:medium%3D%3Dreferral
選用。

filters 查詢字串參數會限制要求傳回的資料。如要使用 filters 參數,請提供要篩選的維度或指標,並在後面加上篩選器運算式。舉例來說,以下查詢會要求資料檢視 (設定檔) 12134ga:pageviewsga: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 傳回網頁時間不是十秒的結果:
filters=ga:timeOnPage!%3D10
> 大於 %3E 傳回網頁時間大於十秒的結果:
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 匯總城市不是 Irvine 的指標:
filters=ga:city!%3DIrvine
=@ 包含子字串 %3D@ 匯總城市含有「York」的情形:
filters=ga:city%3D@York
!@ 不包含子字串 !@ 針對城市不含「York」的匯總指標:
filters=ga:city!@York
=~ 包含與規則運算式相符的項目 %3D~ 匯總城市以「新」開頭的指標匯總指標:
filters=ga:city%3D~%5ENew.*
(%5E 是 ^ 字元編碼的網址,錨點固定至字串開頭)。
!~ 不符合規則運算式 !~ 匯總未以城市為起點的匯總指標:
filters=ga:city!~%5ENew.*

篩選器運算式

篩選運算式有幾項重要規則:

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

合併篩選器

篩選器可用 ORAND 布林邏輯合併。這樣一來,您就能有效延長篩選運算式的長度上限為 128 個字元。

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

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

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

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

AND 運算子是以半形分號 (;) 來定義。 在前方加上 OR 運算子,「可用於」可以在同一個運算式中合併維度和指標。

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

國家/地區為美國,「且」瀏覽器為 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 中要求區隔,請參閱 Segments 開發指南

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

區隔中可用的維度和指標。
並非所有維度和指標都能在區隔中使用。如要查看區隔中可使用哪些維度和指標,請前往 Dimensions and Metrics Explorer


samplingLevel

samplingLevel=DEFAULT
選用。
您可以使用這個參數設定報表查詢的取樣層級 (也就是用於計算結果的工作階段數)。允許的值與網頁介面一致,包括:
  • DEFAULT:傳回回應中的範例大小,兼顧速度和準確度。
  • FASTER:傳回取樣大小的快速回應。
  • HIGHER_PRECISION:使用大型樣本傳回更準確的回應,但這可能會導致回應速度變慢。
如未提供,系統會使用 DEFAULT 的取樣層級。
請參閱「取樣」一節,進一步瞭解如何計算查詢使用的工作階段百分比。

包含空白資料列

include-empty-rows=true
選用。
預設值為 true,如果設為 false,則回應中會省略所有指標值皆為 0 的資料列。例如,如果您在查詢中加入多個指標,則只有在所有指標值都是零時,資料列才會移除。當您提出要求時,且預期有效資料列的數量和預期維度值的數量會大幅減少,這個函式就能派上用場。

起始索引

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

max-results

max-results=100
選用。
要加進此回應的列數上限。您可以將此與 start-index 搭配使用,以擷取部分元素,或單獨使用此方法來限制傳回的元素數量 (從第一個值開始)。如未提供 max-results,查詢會傳回預設最多 1, 000 個資料列。
無論要求數量為何,Analytics Core Reporting API 最多傳回 10,000 列資料。如果維度區隔少於預期的數量,這個模型也可傳回比要求的資料列少。舉例來說,ga:country 的可能值少於 300 個,因此如果只依照國家/地區進行區隔,即使您將 max-results 設為較高的值,也無法取得超過 300 個資料列。

output

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

欄位

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

指定要在單一回應中傳回哪些欄位。如果您只在 API 回應中使用部分欄位,您可以使用 fields 參數指定要納入的欄位。

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

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

prettyPrint

prettyPrint=false
選用。

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


quotaUser

quotaUser=4kh4r2h4
選用。

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

如果兩者皆提供,會覆寫 userIp


回應

如果成功,這項要求會傳回下列定義的 JSON 結構的回應主體。如果 output 參數設為 dataTable,則要求會傳回回應主體,其中定義下方定義的 JSON (資料表) 結構。

注意:「results」是指與查詢相符的整組資料列,「回應」則是指在目前結果頁面上傳回的一組資料列。如果結果總數大於目前回應的頁面大小,這兩者就會不同,如 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 數據分析區隔。
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。 如要進一步瞭解大型查詢的 totalResultsitemsPerPage 說明,請參閱 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 這個資料檢視 (設定檔) 所屬的網站資源內部 ID,例如 UA-30481-1
profileInfo.profileName string 資料檢視 (設定檔) 的名稱。
profileInfo.tableId string 資料檢視 (設定檔) 的資料表 ID,由「ga:」後面加上資料檢視 (設定檔) ID。
containsSampledData boolean 如果回應包含取樣資料,則為「是」。
sampleSize string 用於計算取樣資料的樣本數量。
sampleSpace string 取樣空間總大小。這是指從中選取樣本的可用樣本空間總大小。
columnHeaders[] list 列出維度名稱後接指標名稱的欄標題。維度和指標的順序與透過 metricsdimensions 參數在要求中指定的順序相同。標題數是維度數量 + 指標數量。
columnHeaders[].name string 維度或指標的名稱。
columnHeaders[].columnType string 欄類型。「DIMENSION」或「METRIC」。
columnHeaders[].dataType string 資料類型。維度欄標題只有 STRING 做為資料類型。指標欄標題具有指標值的資料類型,例如 INTEGERPERCENTTIMECURRENCYFLOAT 等。所有可能的資料類型請參閱 中繼資料 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 數據分析區隔。
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。 如要進一步瞭解大型查詢的 totalResultsitemsPerPage 說明,請參閱 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 這個資料檢視 (設定檔) 所屬的網站資源內部 ID,例如 UA-30481-1
profileInfo.profileName string 資料檢視 (設定檔) 的名稱。
profileInfo.tableId string 資料檢視 (設定檔) 的資料表 ID,由「ga:」後面加上資料檢視 (設定檔) ID。
containsSampledData boolean 如果回應包含取樣資料,則為「是」。
sampleSize string 用於計算取樣資料的樣本數量。
sampleSpace string 取樣空間總大小。這是指從中選取樣本的可用樣本空間總大小。
columnHeaders[] list 列出維度名稱後接指標名稱的欄標題。維度和指標的順序與透過 metricsdimensions 參數在要求中指定的順序相同。標題數是維度數量 + 指標數量。
columnHeaders[].name string 維度或指標的名稱。
columnHeaders[].columnType string 欄類型。「DIMENSION」或「METRIC」。
columnHeaders[].dataType string 資料類型。維度欄標題只有 STRING 做為資料類型。指標欄標題具有指標值的資料類型,例如 INTEGERPERCENTTIMECURRENCYFLOAT 等。所有可能的資料類型請參閱 中繼資料 API 回應
totalsForAllResults object 要求指標的總值,以指標名稱和值的鍵/值組合。指標總數的順序與要求中指定的指標順序相同。
dataTable object 可與 Google 圖表搭配使用的資料表物件。
dataTable.cols[] list 維度欄描述元清單,後面接有指標。維度和指標的順序與透過 metricsdimensions 參數在要求中指定的順序相同。欄數是維度數量 + 指標數量。
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 執行查詢。

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

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

取樣

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

您可以設定 samplingLevel 參數,藉此指定要求使用的取樣層級。

如果 Core Reporting API 回應包含取樣資料,則 containsSampledData 回應欄位將為 true。此外,sampleSizesampleSpace 這 2 項屬性將提供查詢的取樣層級相關資訊。使用這 2 個值,即可計算用於查詢的工作階段百分比。舉例來說,如果 sampleSize201,000sampleSpace220,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 則會提供結果中可顯示的資料列數量上限。如果 totalResultsitemsPerPage 的比率高,個別查詢花費的時間可能會超過所需時間。如果您只需要少數資料列 (例如用於顯示),可能會想透過 max-results 參數明確設定回應大小限制。不過,如果應用程式需要處理完整的一組結果,則要求允許的資料列上限可能更有效率。

使用 gzip

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

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