GA4 Data APIの欠けた集計を見分ける新項目

GA4 のデータを API で取り出して、社内のダッシュボードや月次レポート、サイトの人気記事の欄に使っている。ある月から数字が急に小さくなったが、それが本当にアクセスが減ったのか、集計の一部が欠けているだけなのかを、返ってきた行だけでは見分けられない。

2026年9月14日、GA4 Data API の変更履歴（Changelog）に、応答のメタデータへ集計の一部が欠けていることを知らせる項目 dataTruncationReasons を加えた（v1beta と v1alpha）と載りました。欠けている理由の種類と、欠けている日付の範囲が返ります。ただ、API に項目が増えても、使っているクライアントライブラリが古いと、アプリからは見えません。本記事では、API 定義の原文と、Node.js の公式クライアントの版ごとに受け取れるかを試した結果を整理します。

応答に加わった項目

Google が公開している GA4 Data API の API 定義（Discovery 文書、v1beta、revision 20261014）とリファレンスでは、runReport などの応答の metadata（ResponseMetaData）に次の項目があります。

• dataTruncationReasons: 「If set, indicate there is data truncation in the report.」（設定されていれば、レポートでデータの切り捨てがある）

1つの理由（DataTruncationReason）には、次の4つが入ります。

• dataTruncationType: 切り捨ての種類
• dataTruncationDate: この日付より前のデータが切り捨てられている（YYYY-MM-DD）
• dataTruncationDateRanges: 切り捨てられた期間（開始日・終了日、どちらも当日を含む）
• dataTruncationMessage: 説明の文

npm で配布されている googleapis の型定義では、2026年9月24日（UTC）に公開された 182.0.0 で初めてこの項目が現れ、181.0.0 にはありません。

10種類の理由

dataTruncationType の値と、API 定義に書かれた説明は次のとおりです（未指定を除く）。

中小企業のサイト運用で関係しやすいのは、上の3つだと編集部は考えます。プロパティのデータ保持期間より前を含む長い期間の集計、Google 広告の費用とサイトの成果を長い期間で並べる集計、期間の長いレポートを一度に取る処理です。

既存のメタデータと何が違うか

ResponseMetaData には、以前から集計の確からしさに関わる項目がいくつかあります。

• subjectToThresholding: しきい値（少人数のデータを隠す仕組み）の対象のレポートか
• samplingMetadatas: サンプリングされた場合、使ったイベントの割合
• dataLossFromOtherRow: 組み合わせの多いレポートで、一部が「(other)」の行にまとめられたか
• emptyReason: レポートが空の場合の理由

これらは「数字が丸められた・まとめられた」ことを示すもので、期間の一部がまるごと抜けていることを示す項目はありませんでした。dataTruncationReasons は、その抜けた日付を返す点が違います。

古いクライアントでは項目が消える

GA4 Data API を Node.js から使う公式のクライアントは @google-analytics/data です。npm で公開されている各版のパッケージに含まれる定義（proto）を調べると、data_truncation_reasons が入ったのは 2026年9月22日（UTC）公開の 7.2.0 で、7.1.0 にはありません。7系の package.json は、動かす Node.js の条件を 22以上（>=22）としています。

このクライアントは、既定では API との通信を gRPC と protobuf で行います。protobuf では、受け取った側の定義にない項目は、アプリのオブジェクトに現れません。編集部の検証環境で、7.3.0 の定義を使って dataTruncationReasons を含む応答のデータを作り、それを 7.3.0 と 5.2.1 の定義でそれぞれ読みました。

• 7.3.0 の定義: dataTruncationType（DATA_TRUNCATION_TYPE_PROPERTY）、日付、期間、説明がすべて読めた
• 5.2.1 の定義: 同じデータから読めたのは currencyCode だけで、dataTruncationReasons はなかった

これは定義ファイル同士での確認で、実際の GA4 のプロパティから切り捨てのある応答を受け取ったものではありません。それでも、API 側で項目が返っていても、5系のクライアントのままではアプリのコードから見えないことは確かめられました。

当サイトでも、人気記事の欄（直近30日）と、日次の集計用のスクリプト（直近30日・90日）が @google-analytics/data を使っており、package-lock.json で固定されている版は 5.2.1 です。この項目を使うには、Node.js 22以上の環境で 7.2.0 以降へ上げる必要があります。

集計の処理に足す確認

ここからは編集部の提案です。

1. 使っているクライアントの版を確かめる。 Node.js なら npm ls @google-analytics/data。7.2.0 より前なら、Node.js の版と合わせて更新を計画する。メジャー版が2つ上がるため、更新前にほかの変更点も確かめる
2. 応答の metadata を記録する。 行のデータだけ保存している処理は、dataTruncationReasons・subjectToThresholding・samplingMetadatas・dataLossFromOtherRow を一緒に残す
3. 切り捨てがあったら、数字と一緒に表示する。 ダッシュボードやレポートに「この期間の一部は集計に含まれていません（〜まで）」と出し、前年比などの比較から外す
4. 長い期間を一度に取る処理は、期間を分ける。 欠けた期間が返ってきたときに、どの月の数字が影響を受けたかを特定しやすくなる

分析の数字が変わったとき、実際の変化か、計測や集計の問題かを切り分ける考え方はアクセス解析の前年比較が壊れるで、GA4 Data API を使った人気記事の欄の作り方はAstro SSG × GA4 の人気記事ランキングで、GA4 の基本的な指標はGA4で見るべき5つの指標で整理しています。

確認した範囲

2026年10月15日に、GA4 Data API の Discovery 文書（v1beta、revision 20261013）を直接取得し、npm の googleapis 181.0.0・182.0.0 の型定義と、@google-analytics/data 7.1.0・7.2.0・7.3.0 の定義（proto）・package.json を調べました（資料調査）。あわせて、編集部の検証環境（Linux、Node.js v22.22.0、protobufjs 7）で、7.3.0 と 5.2.1 の定義を使った読み取りを1回ずつ確認しました（実機検証）。公開前の2026年10月16日に、GA4 Data API の変更履歴（2026-09-14 の項）とリファレンスの ResponseMetaData、Discovery 文書（revision 20261014）を取得して記述を照合し、7.3.0 と 5.2.1 の定義での読み取りも別の環境（macOS、Node.js v22.19.0）で同じ結果になることを確かめました。GA4 のプロパティへの実際の問い合わせと、各理由が返る条件は確認していません。

GA4 のデータを使った社内向けの集計の仕組みづくりや、既存の集計スクリプトの点検は、開発・AI・自動化のご相談からお問い合わせください。

参考資料

• Google Analytics Data API Changelog（2026-09-14）
• ResponseMetaData（Google Analytics Data API v1beta リファレンス）
• Google Analytics Data API v1beta — Discovery document
• npm registry — @google-analytics/data
• npm registry — googleapis