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 アナリティクス 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 が実行されて、Analytics サービスクラスが読み込まれます。読み込みが完了したら、DOM にある gapi.client.analytics というオブジェクトを使用して、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 パラメータ、つまり table 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
  });
  // ...
}

この例の makeApiCall 関数は、JavaScript クライアント ライブラリが読み込まれた後に呼び出されます。この関数は、内部で 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 として返されます。外側のリストは、すべてのデータ行を表します。内側の各リストは単一の行を表します。行内のセルの順序は、前述した列ヘッダー オブジェクトのフィールドの並びと同じです。

各セルのデータは文字列として返されるため、値を適切なデータタイプに 照らし合わせて解析する場合、各列ヘッダー オブジェクトの 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 ソース