標準のユニバーサルアナリティクス（UA）プロパティでは、2023 年 7 月 1 日をもってデータの処理が停止されました。UA 360 プロパティでは、2024 年 7 月 1 日をもってデータの処理が停止されます。また、Google アナリティクス 4 への移行に伴い、一部の UA 360 の機能はその前にサポート終了となります。Data API を使用して、GA4 プロパティのレポート機能にアクセスします。

このページは Cloud Translation API によって翻訳されました。

Core Reporting API - デベロッパーガイド

このドキュメントでは、Core Reporting API を使用して Google アナリティクスのデータを利用する方法について説明します。

はじめに

Google アナリティクスの標準レポートとカスタムレポートに使用されている表形式のデータには、Core Reporting API を介してアクセスできます。データにアクセスするにはクエリを作成します。このクエリでは、ビュー（旧プロファイル）、開始日と終了日、さらに、表内の列ヘッダーを構成するディメンションと指標を指定します。このクエリを Core Reporting API に送信すると、すべてのデータが表形式で返されます。

この API を初めてご利用になる場合は、Core Reporting API の概要をご覧ください。Core Reporting API の目的と API が提供するデータについて説明しています。

始める前に

このガイドでは、Java、Python、PHP、JavaScript の各プログラミング言語を使用して Google アナリティクス API にアクセスする方法について説明します。

API で利用可能なすべてのプログラミング言語ごとのクライアントライブラリの一覧を、クライアントライブラリページで確認する。
クライアントライブラリを使用せずに API にアクセスする方法については、リファレンスガイドをご覧ください。

各クライアントライブラリは、すべての Core Reporting API データにアクセスするための 1 つの Analytics サービスオブジェクトを提供します。このサービスオブジェクトを作成するには、通常、次の手順に従います。

お使いのアプリケーションを Google API コンソールで登録します。
Google アナリティクスデータへのアクセスを承認します。
Analytics サービスオブジェクトを作成します。

上記の手順を完了していない場合は、いったん Google アナリティクス API についてのチュートリアルをお読みください。このチュートリアルでは、Google Analytics API アプリケーションを作成する最初の手順について説明します。この手順を完了すると、このガイドを使用して実環境で作業できるようになります。

次のコードスニペットは、承認済みのサービスオブジェクトを格納する変数を示したものです。

Java

Analytics analytics = // Read Hello Analytics Tutorial for details.

Python

analytics = # Read Hello Analytics Tutorial for details.

PHP

$client = // Read Hello Analytics Tutorial for details.

// Return results as objects.
$client->setUseObjects(true);

$analytics = new apiAnalyticsService($client);

PHP ライブラリからすべての API の結果が連想配列として返されます。実際のオブジェクトを返すには、上記の例で示すように、クライアントの useObject メソッドを呼び出します。

JavaScript

<script src="https://apis.google.com/js/client.js?onload=loadLib"</script>
<script>
function loadLib() {
  // Handle all the authorization work.
  // Read Hello Analytics Tutorial for details.
  gapi.client.load('analytics', 'v3', makeApiCall);
}
</script>

最初の script タグで、Google API JavaScript ライブラリを読み込みます。読み込みが完了すると、loadLib が実行され、分析サービスクラスが読み込まれます。完了すると、オブジェクト gapi.client.analytics が DOM 内に存在し、Core Reporting API へのクエリに使用できるようになります。

Analytics サービスオブジェクトを作成したら、Core Reporting API にリクエストを送信するための準備は完了です。

注: この Analytics サービスオブジェクトを使用して Management API にアクセスすることもできます。

概要

Core Reporting API を使用するアプリケーションは、一般的に次の 2 つの作業を実行します。

Core Reporting API へのクエリ
API の結果の処理

それぞれについて詳しく見ていきましょう。

Core Reporting API へのクエリ

Core Reporting API へのクエリの作成

Analytics サービスオブジェクトには、Core Reporting API へのクエリを作成するメソッドが含まれています。

各 Core Reporting API クエリには、返すデータを指定する一連のパラメータが含まれます。

最も重要なクエリパラメータの一つは、ids パラメータ（テーブル ID）です。このパラメータは、どの Google アナリティクスのビュー（プロファイル）からデータを取得するかを指定します。値は ga:xxx の形式です。ここで、xxx はビュー（プロファイル）ID です。

Java

Get apiQuery = analytics.data().ga()
    .get(tableId,                  // Table Id.
        "2012-01-01",              // Start date.
        "2012-01-15",              // End date.
        "ga:sessions")               // Metrics.
    .setDimensions("ga:source,ga:keyword")
    .setSort("-ga:sessions,ga:source")
    .setFilters("ga:medium==organic")
    .setMaxResults(25);

Python

api_query = service.data().ga().get(
    ids=TABLE_ID,
    start_date='2012-01-01',
    end_date='2012-01-15',
    metrics='ga:sessions',
    dimensions='ga:source,ga:keyword',
    sort='-ga:sessions,ga:source',
    filters='ga:medium==organic',
    max_results='25')

PHP

private function queryCoreReportingApi() {
  $optParams = array(
      'dimensions' => 'ga:source,ga:keyword',
      'sort' => '-ga:sessions,ga:source',
      'filters' => 'ga:medium==organic',
      'max-results' => '25');

  return $service->data_ga->get(
      TABLE_ID,
      '2010-01-01',
      '2010-01-15',
      'ga:sessions',
      $optParams);
}

このライブラリの get メソッドは、Core Reporting API へのクエリを作成するだけでなく、API へのリクエストを実行します。

JavaScript

function makeApiCall() {
  var apiQuery = gapi.client.analytics.data.ga.get({
    'ids': TABLE_ID,
    'start-date': '2010-01-01',
    'end-date': '2010-01-15',
    'metrics': 'ga:sessions',
    'dimensions': 'ga:source,ga:keyword',
    'sort': '-ga:sessions,ga:source',
    'filters': 'ga:medium==organic',
    'max-results': 25
  });
  // ...
}

この例では、JavaScript クライアントライブラリが読み込まれると makeApiCall 関数が呼び出されます。この関数内で新しい Google アナリティクス API クエリが作成され、オブジェクトが apiQuery 変数に格納されます。

クエリの各パラメータとその目的の全一覧については、Core Reporting API のリファレンスガイドをご覧ください。また、Google アナリティクスから取得するデータは、ディメンションパラメータと指標パラメータで指定できます。完全なリストについては、ディメンションと指標のリファレンスページをご覧ください。

Core Reporting API データリクエストの実行

クエリを定義したら、その execute メソッドを呼び出して、Google アナリティクスサーバーにクエリを送信します。

Java

try {
  apiQuery.execute();
  // Success. Do something cool!

} catch (GoogleJsonResponseException e) {
  // Catch API specific errors.
  handleApiError(e);

} catch (IOException e) {
  // Catch general parsing network errors.
  e.printStackTrace();
}

未加工の API レスポンスにアクセスする場合は、executeUnparsed() メソッドを使用します。

HttpResponse response = apiQuery.executeUnparsed();

Python

try:
  results = get_api_query(service).execute()
  print_results(results)

except TypeError, error:
  # Handle errors in constructing a query.
  print ('There was an error in constructing your query : %s' % error)

except HttpError, error:
  # Handle API service errors.
  print ('There was an API error : %s : %s' %
         (error.resp.status, error._get_reason()))

PHP

  try {
    $results = queryCoreReportingApi();
    // Success. Do something cool!

  } catch (apiServiceException $e) {
    // Handle API service exceptions.
    $error = $e->getMessage();
  }

JavaScript

function makeApiCall() {
  // ...

  apiQuery.execute(handleCoreReportingResults);
}

function handleCoreReportingResults(results) {
  if (!results.error) {
    // Success. Do something cool!
  } else {
    alert('There was an error: ' + results.message);
  }
}

この例は、前述の Core Reporting API に対するクエリを作成する手順の続きです。このステップでは、クエリが実行されます。execute メソッドのパラメータは、API からデータが返されると実行されるコールバック関数への参照です。

API から結果が返されると、コールバック関数が実行され、API からデータが渡されます。エラーが発生した場合、結果には error という名前のプロパティが含まれます。

この例では、error が存在するかどうか、または API が正常に返されたかどうかをチェックします。

クエリが正しく実行されると、リクエストしたデータが API から返されます。エラーが発生すると、API は特定のステータスコードとエラーを説明するメッセージを返します。すべてのアプリケーションがエラーを適切に捕捉して処理する必要があります。

API の結果の処理

Core Reporting API へのクエリが正常に完了すると、API はアナリティクスのレポートデータの他、そのデータに関連した情報を返します。

アナリティクスのレポートデータ

API から返される主なデータは、主に次の 2 種類のデータを含む表と考えることができます。

各列に格納される値のタイプを表すヘッダー
表内のデータ行

列ヘッダーのデータ

API からのレスポンスにはそれぞれ、表のヘッダー情報を表す列ヘッダーフィールドが存在します。このフィールドはオブジェクトのリスト（配列）で、各オブジェクトは列のデータのタイプを表します。リストには、ディメンションの列に続けて指標の列が、元のクエリに指定した順序で表示されます。

Java

private void printColumnHeaders(GaData gaData) {
 System.out.println("Column Headers:");

 for (GaDataColumnHeaders header : gaData.getColumnHeaders()) {
   System.out.println("Column Name: " + header.getName());
   System.out.println("Column Type: " + header.getColumnType());
   System.out.println("Column Data Type: " + header.getDataType());
 }
}

Python

def print_column_headers():
  headers = results.get('columnHeaders')

  for header in headers:
    # Print Dimension or Metric name.
    print 'Column name = %s' % header.get('name'))
    print 'Column Type = %s' % header.get('columnType')
    print 'Column Data Type = %s' % header.get('dataType')

PHP

private function printColumnHeaders(&results) {
  $html = '';
  $headers = $results->getColumnHeaders();

  foreach ($headers as $header) {
    $html .= <<<HTML
Column Name = {$header->getName()}
Column Type = {$header->getColumnType()}
Column Data Type = {$header->getDataType()}
HTML;

  print $html;
}

JavaScript

function printColumnHeaders(results) {
  var output = [];

  for (var i = 0, header; header = results.columnHeaders[i]; ++i) {
    output.push(
        'Name        = ', header.name, '\n',
        'Column Type = ', header.columnType, '\n',
        'Data Type   = ', header.dataType, '\n'
    );
  }

  alert(output.join(''));
}

行データ

API から返される主なデータは、2 次元の文字列 List として返されます。外側のリストはデータのすべての行を表します。内側のリストはそれぞれ 1 行を表し、行内のセルの順序は上記の列ヘッダーオブジェクトのフィールドと同じです。

各セルのデータは文字列として返されるため、各列ヘッダーオブジェクトの DataType フィールドは、文字列値を適切な型に解析するために使用できるため、特に便利です。使用可能なすべてのデータ型については、 Metadata API レスポンスをご覧ください。

次の例では、表のヘッダーと行の両方を出力します。

Java

private void printDataTable(GaData gaData) {
 if (gaData.getTotalResults() > 0) {
   System.out.println("Data Table:");

   // Print the column names.
   for (GaDataColumnHeaders header : gaData.getColumnHeaders()) {
     System.out.format("%-32s", header.getName() + '(' + header.getDataType() + ')');
   }
   System.out.println();

   // Print the rows of data.
   for (List<String> rowValues : gaData.getRows()) {
     for (String value : rowValues) {
       System.out.format("%-32s", value);
     }
     System.out.println();
   }
 } else {
   System.out.println("No Results Found");
 }

Python

def print_data_table(results):
  # Print headers.
  output = []
  for header in results.get('columnHeaders'):
    output.append('%30s' % header.get('name'))
  print ''.join(output)

  # Print rows.
  if results.get('rows', []):
    for row in results.get('rows'):
      output = []
      for cell in row:
        output.append('%30s' % cell)
      print ''.join(output)
  else:
    print 'No Results Found'

PHP

private function printDataTable(&$results) {
  if (count($results->getRows()) > 0) {
    $table .= '<table>';

    // Print headers.
    $table .= '<tr>';

    foreach ($results->getColumnHeaders() as $header) {
      $table .= '<th>' . $header->name . '</th>';
    }
    $table .= '</tr>';

    // Print table rows.
    foreach ($results->getRows() as $row) {
      $table .= '<tr>';
        foreach ($row as $cell) {
          $table .= '<td>'
                 . htmlspecialchars($cell, ENT_NOQUOTES)
                 . '</td>';
        }
      $table .= '</tr>';
    }
    $table .= '</table>';

  } else {
    $table .= '<p>No Results Found.</p>';
  }
  print $table;
}

JavaScript

function printRows(results) {
  output = [];

  if (results.rows && results.rows.length) {
    var table = ['<table>'];

    // Put headers in table.
    table.push('<tr>');
    for (var i = 0, header; header = results.columnHeaders[i]; ++i) {
      table.push('<th>', header.name, '</th>');
    }
    table.push('</tr>');

    // Put cells in table.
    for (var i = 0, row; row = results.rows[i]; ++i) {
      table.push('<tr><td>', row.join('</td><td>'), '</td></tr>');
    }
    table.push('</table>');

    output.push(table.join(''));
  } else {
    output.push('<p>No Results Found</p>');
  }

  alert(output.join(''));
}

レポート情報

API から返されるデータには、主要な表データに加え、レスポンスに関する概要情報が含まれています。これは次の方法で出力することができます。

Java

private void printResponseInfo(GaData gaData) {
  System.out.println("Contains Sampled Data: " + gaData.getContainsSampledData());
  System.out.println("Kind: " + gaData.getKind());
  System.out.println("ID:" + gaData.getId());
  System.out.println("Self link: " + gaData.getSelfLink());
}

Python

def print_response_info(results):
  print 'Contains Sampled Data = %s' % results.get('containsSampledData')
  print 'Kind                  = %s' % results.get('kind')
  print 'ID                    = %s' % results.get('id')
  print 'Self Link             = %s' % results.get('selfLink')

PHP

private function printReportInfo(&$results) {
  $html = <<<HTML
  <pre>
Contains Sampled Data = {$results->getContainsSampledData()}
Kind                  = {$results->getKind()}
ID                    = {$results->getId()}
Self Link             = {$results->getSelfLink()}
</pre>
HTML;

  print $html;
}

JavaScript

function printReportInfo(results) {
  var output = [];

  output.push(
      'Contains Sampled Data  = ', results.containsSampledData, '\n',
      'Kind                   = ', results.kind, '\n',
      'ID                     = ', results.id, '\n',
      'Self Link              = ', results.selfLink, '\n');

  alert(output.join(''));
}

containsSampledData フィールドは、API レスポンスがサンプリングされたかどうかを示すため重要です。サンプリングは、データの結果や、API から返された値が管理画面と一致しない一般的な原因に影響する可能性があります。詳しくは、サンプリングのコンセプトガイドをご覧ください。

ビュー（旧プロファイル）情報

レスポンスにはそれぞれ、そのデータが属しているアカウント、ウェブプロパティ、ビューを示す一連のパラメータが含まれます。

Java

private void printProfileInfo(GaData gaData) {
  GaDataProfileInfo profileInfo = gaData.getProfileInfo();

  System.out.println("Account ID: " + profileInfo.getAccountId());
  System.out.println("Web Property ID: " + profileInfo.getWebPropertyId());
  System.out.println("Internal Web Property ID: " + profileInfo.getInternalWebPropertyId());
  System.out.println("View (Profile) ID: " + profileInfo.getProfileId());
  System.out.println("View (Profile) Name: " + profileInfo.getProfileName());
  System.out.println("Table ID: " + profileInfo.getTableId());
}

Python

def print_profile_info(result):

  info = results.get('profileInfo')
  print 'Account Id          = %s' % info.get('accountId')
  print 'Web Property Id     = %s' % info.get('webPropertyId')
  print 'Web Property Id     = %s' % info.get('internalWebPropertyId')
  print 'View (Profile) Id   = %s' % info.get('profileId')
  print 'Table Id            = %s' % info.get('tableId')
  print 'View (Profile) Name = %s' % info.get('profileName')

PHP

private function printProfileInformation(&$results) {
  $profileInfo = $results->getProfileInfo();

  $html = <<<HTML
<pre>
Account ID               = {$profileInfo->getAccountId()}
Web Property ID          = {$profileInfo->getWebPropertyId()}
Internal Web Property ID = {$profileInfo->getInternalWebPropertyId()}
Profile ID               = {$profileInfo->getProfileId()}
Table ID                 = {$profileInfo->getTableId()}
Profile Name             = {$profileInfo->getProfileName()}
</pre>
HTML;

  print $html;
}

JavaScript

function printProfileInfo(results) {
  var output = [];

  var info = results.profileInfo;
  output.push(

      'Account Id          = ', info.accountId, '\n',
      'Web Property Id     = ', info.webPropertyId, '\n',
      'View (Profile) Id   = ', info.profileId, '\n',
      'Table Id            = ', info.tableId, '\n',
      'View (Profile) Name = ', info.profileName);

  alert(output.join(''));
}

これらの ID は、それぞれ Management API 階層のさまざまなエンティティに対応しています。これらの ID を使用して Management API クエリを作成し、ビュー（プロファイル）に関する追加の構成情報を取得できます。たとえば、 Management API の目標のコレクションに対してクエリを実行し、有効な目標と、その目標に設定されている名前を確認できます。

クエリ情報

Core Reporting API の各レスポンスには、そのレスポンスを作成する際に使用されたすべてのクエリパラメータの値を含むオブジェクトが格納されています。

Java

private void printQueryInfo(GaData gaData) {
  GaDataQuery query = gaData.getQuery();

  System.out.println("Ids: " + query.getIds());
  System.out.println("Start Date: " + query.getStartDate());
  System.out.println("End Date: " + query.getEndDate());
  System.out.println("Metrics: " + query.getMetrics()); // List
  System.out.println("Dimensions: " + query.getDimensions());
  System.out.println("Sort: " + query.getSort()); // List
  System.out.println("Segment: " + query.getSegment());
  System.out.println("Filters: " + query.getFilters());
  System.out.println("Start Index: " + query.getStartIndex());
  System.out.println("Max Results: " + query.getMaxResults());
}

Python

def print_query_info(results):
  query = results.get('query')
  for key, value in query.iteritems():
    print '%s = %s' % (key, value)

PHP

private function printQueryParameters(&$results) {
  $query = $results->getQuery();

  $html = '<pre>';
  foreach ($query as $paramName => $value) {
    $html .= "$paramName = $value\n";
  }
  $html .= '</pre>';

  print $html;
}

JavaScript

function printQuery(results) {
  output = [];

  for (var key in results.query) {
    output.push(key, ' = ', results.query[key], '\n');
  }

  alert(output.join(''));
}

metrics パラメータと sort パラメータはリスト内の値として返され、他のパラメータは文字列として返されます。

ページ設定情報

Core Reporting API リクエストと一致する Google アナリティクスデータの行数は膨大になる可能性があります。Core Reporting API から一度に返されるのはそのサブセットのみで、それを単一のデータページと考えることができます。すべてのデータのページを取得するには、ページ設定フィールドを使用します。

Java

private void printPaginationInfo(GaData gaData) {
  System.out.println("Items Per Page: " + gaData.getItemsPerPage());
  System.out.println("Total Results: " + gaData.getTotalResults());
  System.out.println("Previous Link: " + gaData.getPreviousLink());
  System.out.println("Next Link: " + gaData.getNextLink());
}

Python

def print_pagination_info(results):
  print 'Items per page = %s' % results.get('itemsPerPage')
  print 'Total Results  = %s' % results.get('totalResults')
  print 'Previous Link  = %s' % results.get('previousLink')
  print 'Next Link      = %s' % results.get('nextLink')

PHP

private function getPaginationInfo(&$results) {
  $html = <<<HTML
<pre>
Items per page = {$results->getItemsPerPage()}
Total results  = {$results->getTotalResults()}
Previous Link  = {$results->getPreviousLink()}
Next Link      = {$results->getNextLink()}
</pre>
HTML;

  print $html;
}

JavaScript

function printPaginationInfo(results) {
  var output = [];

  output.push(
      'Items Per Page = ', results.itemsPerPage, '\n',
      'Total Results  = ', results.totalResults, '\n',
      'Previous Link  = ', results.previousLink, '\n',
      'Next Link      = ', results.nextLink, '\n');

  alert(output.join(''));
}

totalResults フィールドは、Google アナリティクスでクエリと一致したデータ行の合計数を表します。これは、レスポンスの 1 ページで返される実際の行数よりも大きくなることがあります。itemsPerPage フィールドは、このページで返される行数を表します。

previousLink パラメータと nextLink パラメータは、前ページまたは次のページが存在する場合にのみ存在します。Core Reporting API から取得できるページが他にもあるかどうかは、これらのリンクをチェックして確認することができます。

すべての結果の合計

前述のページ設定情報のセクションで説明したように、Core Reporting API に対するクエリは、Google アナリティクス内の多数のデータ行と一致しても、データのサブセットのみを返すことがあります。一致したすべての行の指標の合計値が totalsForAllResults オブジェクトで返されます。このデータは平均値の計算に役立ちます。

Java

private void printTotalsForAllResults(GaData gaData) {
  Map totalsMap = gaData.getTotalsForAllResults();

  for (Map.Entry entry : totalsMap.entrySet()) {
    System.out.println(entry.getKey() + " : " + entry.getValue());
  }
}

Python

def print_totals_for_all_results(results):
  totals = results.get('totalsForAllResults')

  for metric_name, metric_total in totals.iteritems():
    print 'Metric Name  = %s' % metric_name
    print 'Metric Total = %s' % metric_total

PHP

private function printTotalsForAllResults(&$results) {
  $totals = $results->getTotalsForAllResults();

  foreach ($totals as $metricName => $metricTotal) {
    $html .= "Metric Name  = $metricName\n";
    $html .= "Metric Total = $metricTotal";
  }

  print $html;
}

JavaScript

function printTotalsForAllResults(results) {
  var output = [];

  var totals = results.totalsForAllResults;
  for (metricName in totals) {
    output.push(
        'Metric Name  = ', metricName, '\n',
        'Metric Total = ', totals[metricName], '\n');
  }

  alert(output.join(''));
}

実用的なサンプル

実際に動作するサンプルを確認するには、各クライアントライブラリの sample ディレクトリにある Core Reporting API のサンプルをご覧ください。

Java

Google API Java クライアントライブラリ Core Reporting API サンプル

Python

Google API Python クライアントライブラリ Core Reporting API サンプル

PHP

Google API PHP クライアントライブラリ Core Reporting API サンプル

JavaScript

Google API JavaScript クライアントライブラリ Core Reporting API サンプル

JavaScript ソース

Core Reporting API - デベロッパー ガイド

はじめに

始める前に

Java

Python

PHP

JavaScript

概要

Core Reporting API へのクエリ

Core Reporting API へのクエリの作成

Java

Python

PHP

JavaScript

Core Reporting API データ リクエストの実行

Java

Python

PHP

JavaScript

API の結果の処理

アナリティクスのレポートデータ

列ヘッダーのデータ

Java

Python

PHP

JavaScript

行データ

Java

Python

PHP

JavaScript

レポート情報

Java

Python

PHP

JavaScript

ビュー（旧プロファイル）情報

Java

Python

PHP

JavaScript

クエリ情報

Java

Python

PHP

JavaScript

ページ設定情報

Java

Python

PHP

JavaScript

すべての結果の合計

Java

Python

PHP

JavaScript

実用的なサンプル

Java

Python

PHP

JavaScript

Core Reporting API - デベロッパーガイド

Core Reporting API データリクエストの実行