このドキュメントでは、Google アナリティクス Data API v1 の高度な機能について説明します。API の詳細なリファレンスについては、API リファレンスをご覧ください。
カスタム定義を一覧表示してレポートを作成する
Data API を使用すると、登録済みのカスタム ディメンションとカスタム指標に関するレポートを作成できます。Metadata API メソッドを使用すると、プロパティに登録されているカスタム定義の API 名を一覧表示できます。これらの API 名は、runReport メソッドへのレポート リクエストで使用できます。
以降のセクションでは、各タイプのカスタム定義の例を示します。これらの例では、GA_PROPERTY_ID
はプロパティ ID に置き換えてください。
イベント スコープのカスタム ディメンション
ステップ 1: プロパティ ID を使用して Metadata API Method をクエリします。
GET https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID/metadata
ステップ 2: レポートの作成対象となるイベント スコープのカスタム ディメンションをレスポンスから探します。ディメンションが存在しない場合は、ディメンションを登録する必要があります。
"dimensions": [
...
{
"apiName": "customEvent:achievement_id",
"uiName": "Achievement ID",
"description": "An event scoped custom dimension for your Analytics property."
},
...
],
ステップ 3: レポート リクエストにカスタム ディメンションを含めます。runReport メソッドに対するリクエストの例を次に示します。
POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
"dateRanges": [{ "startDate": "2020-09-01", "endDate": "2020-09-15" }],
"dimensions": [{ "name": "customEvent:achievement_id" }],
"metrics": [{ "name": "eventCount" }]
}
ユーザー スコープのカスタム ディメンション
ステップ 1: プロパティ ID を使用して Metadata API Method をクエリします。
GET https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID/metadata
ステップ 2: レポートの作成対象となるユーザー スコープのカスタム ディメンションをレスポンスから探します。ディメンションが存在しない場合は、ディメンションを登録する必要があります。
"dimensions": [
...
{
"apiName": "customUser:last_level",
"uiName": "Last level",
"description": "A user property for your Analytics property."
},
...
],
ステップ 3: レポート リクエストにカスタム ディメンションを含めます。runReport メソッドに対するリクエストの例を次に示します。
POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
"entity": { "propertyId": "GA_PROPERTY_ID" },
"dateRanges": [{ "startDate": "7daysAgo", "endDate": "yesterday" }],
"dimensions": [{ "name": "customUser:last_level" }],
"metrics": [{ "name": "activeUsers" }]
}
イベント スコープのカスタム指標
ステップ 1: プロパティ ID を使用して Metadata API Method をクエリします。
GET https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID/metadata
ステップ 2: レポートの作成対象となるイベント スコープのカスタム指標をレスポンスから探します。指標が存在しない場合は、指標を登録する必要があります。
"metrics": [
...
{
"apiName": "customEvent:credits_spent",
"uiName": "Credits Spent",
"description": "An event scoped custom metric for your Analytics property.",
"type": "TYPE_STANDARD"
},
...
],
ステップ 3: レポート リクエストにカスタム指標を含めます。runReport メソッドに対するリクエストの例を次に示します。
POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
"dateRanges": [{ "startDate": "30daysAgo", "endDate": "yesterday" }],
"dimensions": [{ "name": "eventName" }],
"metrics": [{ "name": "customEvent:credits_spent" }]
}
1 つのキーイベントのキーイベント率指標
ステップ 1: プロパティ ID を使用して Metadata API メソッドをクエリします。
GET https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID/metadata
ステップ 2: レポートの作成対象となる 1 つのキーイベントのキーイベント率の指標をレスポンスから探します。キーイベントが存在しない場合は、キーイベントを設定する必要があります。
"metrics": [
...
{
"apiName": "sessionKeyEventRate:add_to_cart",
"uiName": "Session key event rate for add_to_cart",
"description": "The percentage of sessions in which a specific key event was triggered",
},
...
],
ステップ 3: レポート リクエストにキーイベント率の指標を含めます。次の例は、runReport メソッドに対するリクエストのサンプルです。
POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
"dateRanges": [{ "startDate": "30daysAgo", "endDate": "yesterday" }],
"dimensions": [{ "name": "eventName" }],
"metrics": [{ "name": "sessionKeyEventRate:add_to_cart" }]
}
イベント スコープのカスタム指標の平均
ステップ 1: プロパティ ID を使用して Metadata API Method をクエリします。
GET https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID/metadata
ステップ 2: レポートの作成対象となるイベント スコープのカスタム指標の平均値をレスポンスから探します。指標が存在しない場合は、指標を登録する必要があります。
"metrics": [
...
{
"apiName": "averageCustomEvent:credits_spent",
"uiName": "Average Credits Spent",
"description": "The average of an event scoped custom metric for your Analytics property.",
"type": "TYPE_STANDARD"
},
...
],
ステップ 3: カスタム指標の平均値をレポート リクエストに含めます。runReport メソッドに対するリクエストの例を次に示します。
POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
"dateRanges": [{ "startDate": "2020-11-01", "endDate": "2020-11-10" }],
"dimensions": [{ "name": "eventName" }],
"metrics": [{ "name": "averageCustomEvent:credits_spent" }]
}
コホート レポートの例
コホート レポートでは、コホートのユーザー維持率の時系列が作成されます。各 API フィールドの詳細なドキュメントについては、CohortSpec の REST リファレンスをご覧ください。
コホート レポートを作成する
以下に、コホート レポートの例を示します。
- コホートは、
firstSessionDate
が2020-12-01
のユーザーです。これはcohorts
オブジェクトで構成されます。レポート レスポンスのディメンションと指標は、コホートのユーザーのみに基づきます。 - コホート レポートには 3 つの列が表示されます。これは、ディメンション オブジェクトと指標オブジェクトによって構成されます。
- ディメンション
cohort
はコホートの名前です。 - ディメンション
cohortNthDay
は、2020-12-01
からの日数です。 - 指標
cohortActiveUsers
は、まだアクティブなユーザーの数です。
- ディメンション
cohortsRange
オブジェクトは、このコホートの2020-12-01
から2020-12-06
までのイベントデータをレポートに含めるように指定します。- 粒度が
DAILY
の場合、整合性を確保するためにディメンションcohortNthDay
を使用することをおすすめします。
- 粒度が
コホートのレポート リクエストは次のとおりです。
POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
"dimensions": [{ "name": "cohort" }, { "name": "cohortNthDay" }],
"metrics": [{ "name": "cohortActiveUsers" }],
"cohortSpec": {
"cohorts": [
{
"dimension": "firstSessionDate",
"dateRange": { "startDate": "2020-12-01", "endDate": "2020-12-01" }
}
],
"cohortsRange": {
"endOffset": 5,
"granularity": "DAILY"
}
},
}
このリクエストの場合、レポート レスポンスの例は次のようになります。
{
"dimensionHeaders": [
{ "name": "cohort" }, { "name": "cohortNthDay" }
],
"metricHeaders": [
{ "name": "cohortActiveUsers", "type": "TYPE_INTEGER" }
],
"rows": [
{
"dimensionValues": [{ "value": "cohort_0" },{ "value": "0000" }],
"metricValues": [{ "value": "293" }]
},
{
"dimensionValues": [{ "value": "cohort_0" },{ "value": "0001" }],
"metricValues": [{ "value": "143" }]
},
{
"dimensionValues": [{ "value": "cohort_0" },{ "value": "0002" }],
"metricValues": [{ "value": "123" }]
},
{
"dimensionValues": [{ "value": "cohort_0" },{ "value": "0003" }],
"metricValues": [{ "value": "92" }]
},
{
"dimensionValues": [{ "value": "cohort_0" },{ "value": "0005" }],
"metricValues": [{ "value": "86" }]
},
{
"dimensionValues": [{ "value": "cohort_0" },{ "value": "0004" }],
"metricValues": [{ "value": "83" }]
}
],
"metadata": {},
"rowCount": 6
}
このレポートのレスポンスから、このコホート レポートのグラフが返されます。このレポートから得られる分析情報は、このコホートのアクティブ ユーザー数が 1 日目と 2 日目で最も減少していることです。
複数のコホートおよびユーザー維持率の割合
ユーザーの獲得と維持は、ウェブサイトやアプリを成長させる方法です。コホート レポートはユーザーの維持に焦点を当てています。この例のレポートでは、このプロパティの 4 日間のユーザー維持率が 2 週間で 10% 向上したことがわかります。
このレポートを作成するには、3 つのコホートを指定します。最初のコホートの firstSessionDate
は 2020-11-02
、2 番目のコホートの firstSessionDate
は 2020-11-09
、3 番目のコホートの firstSessionDate
は 2020-11-16
です。プロパティのユーザー数は 3 日間の間に異なるため、直接的な cohortActiveUsers
指標ではなく、コホートのユーザー維持率指標 cohortActiveUsers/cohortTotalUsers
を比較します。
これらのコホートのレポート リクエストは次のとおりです。
POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
"dimensions": [{ "name": "cohort" },{ "name": "cohortNthDay" }],
"metrics": [
{
"name": "cohortRetentionFraction",
"expression": "cohortActiveUsers/cohortTotalUsers"
}
],
"cohortSpec": {
"cohorts": [
{
"dimension": "firstSessionDate",
"dateRange": { "startDate": "2020-11-02", "endDate": "2020-11-02" }
},
{
"dimension": "firstSessionDate",
"dateRange": { "startDate": "2020-11-09", "endDate": "2020-11-09" }
},
{
"dimension": "firstSessionDate",
"dateRange": { "startDate": "2020-11-16", "endDate": "2020-11-16" }
}
],
"cohortsRange": {
"endOffset": 4,
"granularity": "DAILY"
}
},
}
このリクエストの場合、レポート レスポンスの例は次のようになります。
{
"dimensionHeaders": [{ "name": "cohort" },{ "name": "cohortNthDay" }],
"metricHeaders": [{
"name": "cohortRetentionFraction",
"type": "TYPE_FLOAT"
}
],
"rows": [
{
"dimensionValues": [{ "value": "cohort_0" },{ "value": "0000" }],
"metricValues": [{ "value": "1" }]
},
{
"dimensionValues": [{ "value": "cohort_1" },{ "value": "0000" }],
"metricValues": [{ "value": "1" }]
},
{
"dimensionValues": [{ "value": "cohort_2" },{ "value": "0000" }],
"metricValues": [{ "value": "1" }]
},
{
"dimensionValues": [{ "value": "cohort_2" },{ "value": "0001" }],
"metricValues": [{ "value": "0.308" }]
},
{
"dimensionValues": [{ "value": "cohort_1" },{ "value": "0001" }],
"metricValues": [{ "value": "0.272" }]
},
{
"dimensionValues": [{ "value": "cohort_2" },{ "value": "0002" }],
"metricValues": [{ "value": "0.257" }]
},
{
"dimensionValues": [{ "value": "cohort_0" },{ "value": "0001" }],
"metricValues": [{ "value": "0.248" }]
},
{
"dimensionValues": [{ "value": "cohort_2" },{ "value": "0003" }],
"metricValues": [{ "value": "0.235" }]
},
{
"dimensionValues": [{ "value": "cohort_2" },{ "value": "0004" }],
"metricValues": [{ "value": "0.211" }]
},
{
"dimensionValues": [{ "value": "cohort_1" },{ "value": "0002" }],
"metricValues": [{ "value": "0.198" }]
},
{
"dimensionValues": [{ "value": "cohort_0" },{ "value": "0002" }],
"metricValues": [{ "value": "0.172" }]
},
{
"dimensionValues": [{ "value": "cohort_1" },{ "value": "0003" }],
"metricValues": [{ "value": "0.167" }]
},
{
"dimensionValues": [{ "value": "cohort_1" },{ "value": "0004" }],
"metricValues": [{ "value": "0.155" }]
},
{
"dimensionValues": [{ "value": "cohort_0" },{ "value": "0003" }],
"metricValues": [{ "value": "0.141" }]
},
{
"dimensionValues": [{ "value": "cohort_0" },{ "value": "0004" }],
"metricValues": [{ "value": "0.118" }]
}
],
"metadata": {},
"rowCount": 15
}
このレポートのレスポンスから、このコホート レポートのグラフが表示されます。このレポートから得られる分析情報は、4 日間のユーザー維持率が 2 週間で 10% 増加したことです。firstSessionDate
が 2020-11-16
の後半コホートの保持率は、firstSessionDate
が 2020-11-02
の前半コホートの保持率を上回っています。
週次コホート、および他の API 機能でのコホートの使用
ユーザーの行動の 1 日あたりのばらつきを除外するには、週次コホートを使用します。週単位のコホート レポートでは、同じ週に firstSessionDate
を持つすべてのユーザーがコホートを形成します。週は日曜日から始まり、土曜日に終わります。また、このレポートでは、コホートをスライスして、ロシアでアクティビティがあったユーザーとメキシコでアクティビティがあったユーザーを比較しています。このスライスでは、country
ディメンションと dimensionFilter
を使用して、2 つの国のみを考慮します。
これらのコホートのレポート リクエストは次のとおりです。
POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
"dimensions": [
{ "name": "cohort" },
{ "name": "cohortNthWeek" },
{ "name": "country" }
],
"metrics": [{ "name": "cohortActiveUsers" }],
"dimensionFilter": {
"filter": {
"fieldName": "country",
"inListFilter": {
"values": [ "Russia", "Mexico" ]
}
}
},
"cohortSpec": {
"cohorts": [
{
"dimension": "firstSessionDate",
"dateRange": {
"startDate": "2020-10-04",
"endDate": "2020-10-10"
}
}
],
"cohortsRange": {
"endOffset": 5,
"granularity": "WEEKLY"
}
},
}
このリクエストの場合、レポート レスポンスの例は次のようになります。
{
"dimensionHeaders": [
{ "name": "cohort" },
{ "name": "cohortNthWeek" },
{ "name": "country" }
],
"metricHeaders": [
{ "name": "cohortActiveUsers", "type": "TYPE_INTEGER" }
],
"rows": [
{
"dimensionValues": [
{ "value": "cohort_0" },{ "value": "0000" },{ "value": "Russia" }
],
"metricValues": [{ "value": "105" }]
},
{
"dimensionValues": [
{ "value": "cohort_0" },{ "value": "0000" },{ "value": "Mexico" }
],
"metricValues": [{ "value": "98" }]
},
{
"dimensionValues": [
{ "value": "cohort_0" },{ "value": "0001" },{ "value": "Mexico" }
],
"metricValues": [{ "value": "35" }]
},
{
"dimensionValues": [
{ "value": "cohort_0" },{ "value": "0002" },{ "value": "Mexico" }
],
"metricValues": [{ "value": "24" }]
},
{
"dimensionValues": [
{ "value": "cohort_0" },{ "value": "0001" },{ "value": "Russia" }
],
"metricValues": [{ "value": "23" }]
},
{
"dimensionValues": [
{ "value": "cohort_0" },{ "value": "0004" },{ "value": "Mexico" }
],
"metricValues": [{ "value": "17" }]
},
{
"dimensionValues": [
{ "value": "cohort_0" },{ "value": "0003" },{ "value": "Mexico" }
],
"metricValues": [{ "value": "15" }]
},
{
"dimensionValues": [
{ "value": "cohort_0" },{ "value": "0005" },{ "value": "Mexico" }
],
"metricValues": [{ "value": "15" }]
},
{
"dimensionValues": [
{ "value": "cohort_0" },{ "value": "0002" },{ "value": "Russia" }
],
"metricValues": [{ "value": "3" }]
},
{
"dimensionValues": [
{ "value": "cohort_0" },{ "value": "0003" },{ "value": "Russia" }
],
"metricValues": [{ "value": "1" }]
},
{
"dimensionValues": [
{ "value": "cohort_0" },{ "value": "0004" },{ "value": "Russia" }
],
"metricValues": [{ "value": "1" }]
}
],
"metadata": {},
"rowCount": 11
}
このレポートのレスポンスに、このコホート レポートのグラフが続きます。このレポートによると、この宿泊施設は、メキシコでアクティビティがあるユーザーの維持率が、ロシアでアクティビティがあるユーザーの維持率よりも高いです。
比較
比較を使用すると、データのサブセットを並べて評価できます。比較を定義するには、レポート定義で comparisons
フィールドを指定します。Data API の比較機能は、Google アナリティクスのフロントエンドの比較機能に似ています。
各 API フィールドの詳細については、比較用の REST リファレンスをご覧ください。
比較を作成する
比較するデータセットごとに個別の比較を作成できます。たとえば、アプリのデータとウェブのデータを比較するには、Android と iOS のデータ用の比較と、ウェブデータ用の比較を個別に作成することが可能です。
次に、2 つの比較を定義し、アクティブ ユーザーを国別に返すレポートの例を示します。
「アプリ トラフィック」という名前の最初の比較では、inListFilter
を使用して、値が「iOS」と「Android」の platform
ディメンションと一致させています。2 つ目の比較「ウェブ トラフィック」では、stringFilter
を使用して platform
ディメンションを「ウェブ」と照合しています。
POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
"comparisons": [
{
"name": "App traffic",
"dimensionFilter": {
"filter": {
"fieldName": "platform",
"inListFilter": {
"values": [
"iOS",
"Android"
]
}
}
}
},
{
"name": "Web traffic",
"dimensionFilter": {
"filter": {
"fieldName": "platform",
"stringFilter": {
"matchType": "EXACT",
"value": "web"
}
}
}
}
],
"dateRanges": [
{
"startDate": "2024-05-01",
"endDate": "2024-05-15"
}
],
"dimensions": [
{
"name": "country"
}
],
"metrics": [
{
"name": "activeUsers"
}
]
}
比較機能を使用するすべてのリクエストで、生成されたレポートに comparison
フィールドが自動的に追加されます。このフィールドには、リクエストで指定された比較の名前が含まれます。
比較を含むレスポンスのサンプル スニペットを次に示します。
{
"dimensionHeaders": [
{
"name": "comparison"
},
{
"name": "country"
}
],
"metricHeaders": [
{
"name": "activeUsers",
"type": "TYPE_INTEGER"
}
],
"rows": [
{
"dimensionValues": [
{
"value": "Web traffic"
},
{
"value": "United States"
}
],
"metricValues": [
{
"value": "638572"
}
]
},
{
"dimensionValues": [
{
"value": "Web traffic"
},
{
"value": "Japan"
}
],
"metricValues": [
{
"value": "376578"
}
]
},
{
"dimensionValues": [
{
"value": "App traffic"
},
{
"value": "United States"
}
],
"metricValues": [
{
"value": "79527"
}
]
},
...
],
...
}