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 サービス オブジェクトを提供します。このサービス オブジェクトを 作成するには、通常、次の手順に従います。

  1. お使いのアプリケーションを Google API コンソールで登録します。
  2. Google アナリティクス データへのアクセスを承認します。
  3. 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 Analytics 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 行を表します。1 つの行内のセルの順序は、上記の列ヘッダー オブジェクトのフィールドと同じです。

各セルのデータは文字列として返されるため、各列ヘッダー オブジェクトの DataType フィールドは、文字列値を適切な型に解析する際に使用できるため特に有用です。可能性のあるすべてのデータタイプについては、メタデータ 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 ソース