記事一覧に戻る

Google Analytics 4(GA4) のAPIを実行する方法

はじめに

Google Analytics 4 (GA4)は、Google社が提供しているウェブサイトのアクセス解析サービスです。ページ別のアクセス数や、ユーザの地域、デバイスやブラウザといった情報を確認できます。

多くのウェブサイトで利用されています。私も例に漏れず利用しており、日々のアクセス数の推移に一喜一憂しています。

GA4は、ウェブサイトやスマホのアプリから情報の確認が出来ますが、プログラムから情報するためのAPIも公開されています。

他のウェブサイトでよく見かける、「アクセス数上位のページへのリンク」をこのサイトでも実装したいな～と思っていたので、このAPIを使って作ってみました。このページのサイド・バー（スマホの場合はページ下部）にある「人気記事」がそうです。

今回は、このAPI（Google Analytics Data API v1）の利用方法を紹介します。

この記事の内容

PythonでGoogle Analytics Data API v1（以下、Data API）を使って、Google Analytics 4 (以下、GA4)のデータを取得する方法を解説します。

Google社のアクセスツールは以前はUniversal Analyticsがありましたが、2023年7月1日から順次データの収集は停止されていくことになっています。GA4はその後継サービスになります。

Data APIはGA4に対応したAPIなので、Universal Analyticsのデータの取得はできないので、ご注意ください。

また、GA4の使い方や設定方法は対象外となります。

前提

GA4の設定について

既に情報を取得したいサイトにGA4の設定が済んでいることを前提とします。

APIの実行環境について

Pythonで紹介します。

私の環境は以下の通りです。

> py --version
Python 3.9.6

後述しますが、別途Google社が提供するクライアント・ライブラリのインストールが必要です。これを利用するため、3.7以降のバージョンである必要があります。

なお、今回はPythonで紹介しますが、他の言語でもAPIの利用は可能です。

Google Analytics Data API v1（Data API）について

Data APIの機能について

先述のとおり、Data APIはGA4のデータを取得するためのAPIです。Universal AnalyticsからGA4の移行が始まった段階ですので、Data APIも新しいサービスと言えます。そのためか、2023年8月時点で、Data APIの機能は全てアルファかベータです。

公式ドキュメントで、アルファとベータについて以下のように説明されています：

アルファ版

アルファ版チャネルの機能は、まだプレビュー版です。Google は今後の変更について通知する予定ですが、API が一般公開される前に互換性を破る変更が発生する可能性があります。

ベータ版

このチャネルでは互換性を破る変更は予定されていません。一般提供前のプロダクトについてはサポートが制限され、一般提供前のプロダクトの変更は、他の一般提供前のバージョンと互換性がない可能性があります。

ベータ版は互換性が保たれる予定ですが、アルファ版はその保証がない点は押さえておいた方が良いですね。

この記事ではベータの機能の一部を紹介します。

APIのデザインについて

これは私が面食らったというだけなのですが、、、

私が今まで利用したことのあるAPIは、所謂REST APIと呼ばれるものでした。指定されたURLにHTTP(S)のGETやPOSTを実行するとデータを返してくれるタイプのやつです。なので、APIのドキュメントは「このURLにBodyにJSONで〇〇してPOSTして」のようなことが書かれていると思っていました。しかしData APIのドキュメントには、そのような記載が見当たりません。

調べてみると、gRPCというフレームワークを使ってAPIのデザインがされているようです。基本、Google製のAPIはgRPCを利用しているみたいですね。HTTP/2をベースにした技術のようで、REST APIとは違い、クライント側でHTTPの規格を意識せずに利用できるように設計されているようです。

このページの内容と直接関係はありませんが、興味がある方はgRPCのドキュメントをご覧ください。

Data API利用までの流れ

ざっくりと、利用するまでの手順は以下のような流れになります。

  1. サービス・アカウントを作成し、認証ファイル(.json)をダウンロード
  2. GA4にサービス・アカウントをユーザ登録
  3. Googleが配付しているクライアント・ライブラリをインストール
  4. 環境変数の設定

1. 認証ファイルの取得

まず、サービス・アカウントの作成と認証ファイルの取得を行います。

API Quickstartを開き、「Enable the Google Analytics Data API v1」ボタンを押します。

enable-button

子画面が開くので、任意のプロジェクト名を入力し、Yesにチェックを入れて利用規約に同意し、Nextボタンを押します。私はプロジェクト名はzenryokukunにしました。

enable-info

Data APIのサービス・アカウント作成の処理が流れます。少し待つと認証ファイルのダウンロードボタンが出てきます。押すと、JSONファイルがダウンロードされます。中身は編集せず、大切に取っておきましょう。なお、ファイル名は分かりやすいものに変えてＯＫです。私はcredentials.jsonにしました。

download-key

これで、サービス・アカウントの作成と認証ファイルの取得は完了です！

2. GA4に登録

次に、作成したサービス・アカウントをGA4にユーザ登録します。

ダウンロードした認証ファイルに、"client_email"というメールアドレス項目があると思います。その値をコピーしておきます。「XXXXXX@iam.gserviceaccount.com」のような値になっているはずです。

Google Analyticsにログインし、「管理」→「プロパティのアクセス管理」をクリックします。

ga4-access

「プロパティのアクセス管理」画面が開くので、右上の青色の＋（プラス）マークを押し、「ユーザを追加」をクリックします。

ga4-add-user

「役割とデータ制限の追加」画面が開くので、「メールアドレス」欄に認証ファイルからコピーしたメールアドレスを貼り付けます。「直接の役割とデータ制限」で、用途に応じたアクセス権を選択します。試しにAPIを実行するだけであれば、「閲覧者」で十分のようです。私も「閲覧者」で登録しています。

アクセス権を選択したら、右上の「追加」をクリックします。

ga4-set-address

処理が終わると再度「プロパティのアクセス管理」画面が開きます。さきほど追加したユーザが表示されているか確認します。

ga4-check-user

表示されていたら、完了です！

3. クライント・ライブラリのインストール

主要言語別にクライアント・ライブラリが用意されています。Python用ライブラリのインストール手順はGithubに記載されています。

手順と言っても、以下を実行するだけです。venvで仮想環境にインストールすることも出来ますが、脱線するのでvenvは割愛します。

pip3 install google-analytics-data

ちなみに、ライブラリはサードパーティ製ではなく、Google社が配付しているものです。だいぶ読みにくいですが、公式ドキュメントもあります。

4. 環境変数の設定

Data APIを使うためには、GOOGLE_APPLICATION_CREDENTIALSという環境変数に、認証ファイル（.jsonファイル）のフルパスを設定する必要があります。

コマンドラインから設定しても良いですが、今回はpythonのスクリプト内で、APIを実行する時に環境変数を設定したいと思います。

例えば、pythonのスクリプト名がmain.pyで、認証ファイル（credentials.json）が同じ階層にあったとします。環境変数を設定するスクリプトは以下のようになります。

import os

# 認証ファイル（credentials.json）の絶対パスを設定。
# 本ファイルと同階層に配置されているものとします。
CREDENTIAL = os.path.join(os.path.dirname(__file__), "credentials.json")

# 環境変数GOOGLE_APPLICATION_CREDENTIALSにcredentials.jsonのパスを設定
os.environ["GOOGLE_APPLICATION_CREDENTIALS"] = CREDENTIAL

APIの実行

サンプル

API Quickstartのスクリプトを参考にしています（ほぼ同じ）。

2023-07-31～本日の期間で、地域（city）別のアクティブユーザ数を取得するサンプルです。

なお、冒頭に環境変数の設定で紹介したスクリプトを差し込んでいます。

import os
from google.analytics.data_v1beta import BetaAnalyticsDataClient
from google.analytics.data_v1beta.types import (
    DateRange,
    Dimension,
    Metric,
    RunReportRequest,
)

# 認証ファイル（credentials.json）の絶対パスを設定。
# 本ファイルと同階層に配置されているものとします。
CREDENTIAL = os.path.join(os.path.dirname(__file__), "credentials.json")

# 環境変数GOOGLE_APPLICATION_CREDENTIALSにcredentials.jsonのパスを設定
os.environ["GOOGLE_APPLICATION_CREDENTIALS"] = CREDENTIAL

# GA4のプロパティIDを設定。
# 不明な場合、Google AnalyticsのWebページで「プロパティID」と検索すれば表示されます。
property_id = "YOUR-GA4-PROPERTY-ID"

def sample_run_report():
    """Runs a simple report on a Google Analytics 4 property."""

    # Using a default constructor instructs the client to use the credentials
    # specified in GOOGLE_APPLICATION_CREDENTIALS environment variable.
    client = BetaAnalyticsDataClient()

    request = RunReportRequest(
        property=f"properties/{property_id}",
        dimensions=[Dimension(name="city")],
        metrics=[Metric(name="activeUsers")],
        date_ranges=[DateRange(start_date="2023-07-31", end_date="today")],
    )
    response = client.run_report(request)

    print("Report result:")
    for row in response.rows:
        print(row.dimension_values[0].value, row.metric_values[0].value)

sample_run_report()

実行結果

上記の実行結果は、私のアカウントだと以下のようになります。

Report result:
Koto City 6
Ota City 6
Shinjuku City 6
Chiyoda City 5
(not set) 4
Minato City 4
Osaka 4

他の地域もあるのですが、長いので省略して一部だけ載せています。

解説

以下、APIの実行サンプルの解説を行います。

ポイントになるのは、変数property_idと、BetaAnalyticsDataClient, RunReportRequest, Dimension, Metric, DateRangeといったクライアント・ライブラリの機能です。

全体の流れとしては、RunReportRequestでAPIのリクエスト・オブジェクトを作って、BetaAnalyticsDataClientのrun_reportメソッドのパラメタに指定して実行するだけなので、案外シンプルです。

変数property_idについて

スクリプト中に出てくる変数property_idに設定する値は、ご自身のGA4のプロパティIDです。不明な場合、Google Analytics上部の検索バーに「プロパティID」と入力すれば、表示されます。

check-property_id

BetaAnalyticsDataClient

BetaAnalyticsDataClientは、APIを実行するクライアントのコンストラクタです。今回は環境変数で認証ファイルのパスを設定しているため、基本はパラメタなしで大丈夫です。client = BetaAnalyticsDataClient()のように初期化すれば問題ありません。

クライアントのオプションやトランスポート等の指定も出来るようですが、応用的な使い方と思われるのと、私自身も試せていないので割愛します。

RunReportRequest

RunReportRequestはリクエストを作成してくれる関数です。ここで作成したリクエストを、後述するclient.run_reportのパラメタに指定することで、APIが実行されます。

サンプルの以下の部分です。

request = RunReportRequest(
    property=f"properties/{property_id}",
    dimensions=[Dimension(name="city")],
    metrics=[Metric(name="activeUsers")],
    date_ranges=[DateRange(start_date="2023-07-31", end_date="today")],
)

RunReportRequestはproperty_id, dimensions, metrics, date_rangesの4つのパラメタを受け取っています。クライアント・ライブラリの機能がてんこ盛りです。

property_idパラメタ

property_idは、先述したGA4のプロパティIDです。「"properties/自身のプロパティID"」のようなフォーマットで指定してあげるだけです。

metricsパラメタ、dimensionsパラメタ

metricsには、Metricオブジェクトを配列で指定し、dimensionsにはDimensionオブジェクトを配列で指定します。GA4で良く目にする、ディメンションと指標（メトリック）のことです。APIで取得したいディメンションと指標の組み合わせを、ここで指定する訳ですね。

Metricオブジェクト、Dimensionオブジェクトは後述します。

date_rangesパラメタ

date_rangesには、DateRangeオブジェクトを配列で指定します。開始日と指定日の指定なので、ここは直感的かと思います。

DateRangeオブジェクトは後述します。

Dimension

RunReportRequestのdimensionsパラメタに指定するオブジェクトです。GA4でよく出てくるディメンションのことです。「地域」、「ブラウザ」、「アクセスのあったURL」等、APIで取得したいデータの属性を表すオブジェクトとなります。

ディメンションは公式のヘルプセンターで以下のように説明されています。

ディメンションとは、データの属性のことです。データを説明するもので、通常は数字ではなくテキストです。

地域（city）やURL（fullPageUrl）、OS（operatingSystem）等の指定が可能です。

Dimension(name="ディメンション名")のように指定します。

ディメンションの一覧は以下のリンクから確認できます。

Metric

RunReportRequestのmetricsパラメタに指定するオブジェクトです。GA4では、日本語だと「指標」と訳されているかと思います。「はじめて訪れた人の数」、「ページビュー数」のように、取得したい「値」を表すオブジェクトです。

こちらは、公式のヘルプセンターでは以下のように説明されています。

指標とは、平均、比率、パーセンテージなどの定量的測定値のことです。テキストではなく必ず数字になります。指標を理解する一つの方法は、指標には算術演算を適用できるという点です。

アクティブユーザ数(activeUsers)、ページビュー数（screenPageViews）の指定が可能です。

Metric(name="指標名")のように指定します。

Metricに指定が可能な値は以下のリンクから確認できます。

DateRange

RunReportRequestのdate_rangesパラメタに指定するオブジェクトです。取得したいデータの期間の開始日と終了日を表すオブジェクトです。

DateRange(start_date="2022-02-01",end_date="2022-02-02")のように、対象とする期間の開始日（start_date）と終了日（end_date）を指定して使います。基本はYYYY-MM-DDの形式で渡しますが、"today"、"yesterday"、"5daysAgo"のような指定も可能です。

client.run_report

BetaAnalyticsDataClientのrun_reportで、APIの実行を行います。パラメタにはRunReportRequestで生成したリクエスト・オブジェクトを指定します。ここはサンプルの通りで、とてもシンプルです。

他にも、タイムアウトやメタデータ等のパラメータを渡すことも可能ですが、私もまだ使ったことがないので割愛します。

変数response

client.run_reportの実行結果をresponse変数にセットしています。APIの実行結果が入ります。

レスポンスの型は、Google Analytics Data API (GA4)のドキュメントに載っています。抜粋すると以下のとおりです。

{
  "dimensionHeaders": [
    {
      object (DimensionHeader)
    }
  ],
  "metricHeaders": [
    {
      object (MetricHeader)
    }
  ],
  "rows": [
    {
      object (Row)
    }
  ],
  "totals": [
    {
      object (Row)
    }
  ],
  "maximums": [
    {
      object (Row)
    }
  ],
  "minimums": [
    {
      object (Row)
    }
  ],
  "rowCount": integer,
  "metadata": {
    object (ResponseMetaData)
  },
  "propertyQuota": {
    object (PropertyQuota)
  },
  "kind": string
}

注意点

型の説明の前に注意点です。

ドキュメントでは、あくまで型をJSONで表現しているだけです。実際にPythonで扱う際には、response["rows"]のようにディクショナリとして扱うのではなく、response.rowsとする必要があります。

また、実際のライブラリでは、プロパティ名はその言語の一般的なネーミング・ルールに沿って実装されているようです。例えば、Pythonでは、dimensionHeadersは、dimension_headersのように実装されています。

レスポンスの型について

上記で抜粋した型を見ると、行数やメタデータや、リクエスト時のディメンションの情報等、色々あります。

実行結果が格納されているのはrowsです。rowsは、Row型の配列であることが分かります。

Row型はJSONで表現すると以下のような型です。

{
  "dimensionValues": [
    {
      object (DimensionValue)
    }
  ],
  "metricValues": [
    {
      object (MetricValue)
    }
  ]
}

dimensionValuesとmetricValuesが、それぞれDimensionValue型の配列とMetricValue型の配列として表現されます。

DimensionValueとMetricValue型は、valueプロパティが存在するだけです。

よって、responseの１行目のディメンションとメトリクスを参照するには、以下のような記述となります。

first_dimension = response.rows[0].dimension_values[0].value
first_metric = response.rows[0].metric_values[0].value
# メトリクスが複数ある場合、２つ目のメトリクス
second_metric = response.rows[0].metric_values[1].value

ディメンションやメトリクスは複数指定できるので、dimension_valuesやmetric_valuesの添え字で指定します。RunReportRequestで指定した順に格納されています。

DimensionとMetricの組み合わせ

APIの実行のサンプルは、ディメンションは「地域」で、メトリクスは「アクティブユーザ」でした。ここで、別のディメンションとメトリクスの組み合わせを考えてみたいと思います。

例えば、「ページ（url）単位のアクティブユーザ数とページビュー数」を取得するとします。ディメンションは「fullPageURL」、メトリクスは「activeUsers、screenPageViews」を使えばよさそうです。

APIを実行するsample_run_report関数は下のようになります。

def sample_run_report():
    """Runs a simple report on a Google Analytics 4 property."""

    # Using a default constructor instructs the client to use the credentials
    # specified in GOOGLE_APPLICATION_CREDENTIALS environment variable.
    client = BetaAnalyticsDataClient()

    request = RunReportRequest(
        property=f"properties/{property_id}",
        dimensions=[Dimension(name="fullPageUrl")],
        metrics=[Metric(name="activeUsers"), Metric(name="screenPageViews")],
        date_ranges=[DateRange(start_date="5daysAgo", end_date="today")],
    )
    response = client.run_report(request)

    print("Report result:")
    for row in response.rows:
        print(row.dimension_values[0].value, row.metric_values[0].value, row.metric_values[1].value)

上記のとおり、1つのディメンションに対し、複数のメトリクスを指定することも可能です。

今回はメトリクスが２つあるので、最後のprint関数でrow.metric_value[0].valueとrow.metric_value[1].valueの2つのメトリクスを表示させています。１つ目（添え字:0）がアクティブ・ユーザ数で、２つ名（添え字:1）がページビュー数に対応しています。

実行結果は以下のとおりです。

www.zenryoku-kun.com/post/nextjs-app-router 137 190
www.zenryoku-kun.com/post/twitter-api 49 65
www.zenryoku-kun.com/post/fitbit-api 44 63
www.zenryoku-kun.com/post/nextjs13-image 27 41
www.zenryoku-kun.com/post/node-ubuntu 18 22
www.zenryoku-kun.com/post/202210_1 13 13
www.zenryoku-kun.com/post/pm2 12 17
www.zenryoku-kun.com/post/drag-and-drop 7 8

しかし、ディメンションとメトリクスの全ての組み合わせが指定できる訳ではありません。一応、こちらのGA4 Dimensions & Metrics Explorerで組み合わせのチェックが可能です。ちょっと私も使いこなせていませんが、、、このあたりは色々試しながら把握していきたいと思います。

後、複数のディメンションを指定するとエラーになってしまいます。これは、私の使い方の問題かもしれませんが、、、ただ、レスポンスのrow.metric_valuesが指定したディメンションに対する指標の１次元配列であることを踏まえると、やはり１つのディメンションにしか対応していない気がします。このあたりは、何か新しいことが分かったら追記したいと思います。

最後に

Google Analytics Data API v1(Data API)を使うために必要な事前準備と、Pythonを使って実際にAPIを実行する方法を解説しました。

実際に触ってみると、まだまだGoogle Analytics 4自体を使いこなせていないな～と感じました。カスタム・レポートとかも作れるようですし、APIでそれを取得することも可能なようです。

私の用途としては、とりあえずはこのサイトでアクセス数の多い記事のリンクを作成するだけですが、これからももっと使ってみようと思います。

しかし、gRPCは初めて使いましたが、Google Photoとか他のGoogleサービスも使っているようですね。毎度ライブラリをインストールするのは面倒ですが、今後増えていくかもしれないので、慣れていく必要がありそうです。

参考

記事一覧に戻る
全力君より、愛を込めて。
2024 全力君
ABOUT
削り削って研ぎ澄ませ、最先端の感性を。
そしてLANケーブルに、注ぎ込め！
Feel free to follow me.
Site Policy