レポーティングのクエリ文字列パラメーター

以下は、v3 AnalyticsReporting API用の全クエリ文字列パラメーターのリファレンス詳細です。

すべてのパラメーター名で大文字小文字が区別されます。

クエリ文字列全体を必ずURLエンコードしてください。

GETレポートの通常シンタックス

ルートとクエリ文字列の基本シンタックスは以下のとおりです。読みやすくするため、1行のリクエストが複数行に分かれています。

[GET] /v3/analytics/reports/?
            report_type=type
            &dimensions=dimensions
            &metrics=metrics
            &filters=filter_type=='filter_value'
            &start_date=date
            &end_date=date
            &other_parms
            &api_key=your_api_key
         
  • 必須クエリ文字パラメーター(太文字で表示)はreport_type, start_dateおよびapi_keyです。
  • ディメンションが指定されていない場合、全ディメンションのすべての値が返されます。
  • 一度に3つのディメンションまで指定できます。
  • メトリックが指定されていない場合、すべてのメトリックが返されます。
Note: 現時点で、report_typeの唯一の有効な値はパフォーマンスです。

長いクエリPOSTをレポートする一般的なシンタックス

230文字のHTTP GET仕様限度を超えるクエリパラメーターのクエリについては、POSTリクエストを使ってください。一部のブラウザとHTTPクライアントは230文字以上に対応している場合がありますが、当社はHTTP GET仕様に違反しているクエリにサポートを提供していません。POSTリクエストについては、クエリ文字パラメーターの代わりにリクエスト本文にJSONオブジェクトをパスします。

[POST] /v3/analytics/reports

{
    "report_type":"type",
    "dimensions":"dimensions",
    "metrics":"metrics",
    "filters":"(filter_type==\"filter_value\")",
    "start_date":"date",
    "end_date":"date",
    "other_parms":"other_param_value",
    "api_key":"your_api_key"
}
         
パラメーター 説明 必須

report_type

レポートタイプを指定します。

有効な値:performance

デフォルト:なし

例: report_type=performance

はい

start_date

開始日はYYYY-MM-DDと指定されています

start_dateの値はプロバイダーのタイムゾーンです。

デフォルト:なし

制限:2フィルターでは最大1年(366日)、3フィルターでは最大1か月(31日)の範囲でクエリを実行できます。

例: start_date=2014-10-28

はい

end_date

終了日はYYYY-MM-DDと指定されています

注記:終了日は含まれません。つまり、応答には終了日前日までのデータが返されます。

デフォルト:プロバイダーのタイムゾーンでの明日の日付。

制限:2フィルターでは最大1年(366日)、3フィルターでは最大1か月(31日)の範囲でクエリを実行できます。

例:2014年10月29日までの全データを取得するには:end_date=2014-10-29

いいえ

metrics

メトリック名のカンマ区切りリスト。

デフォルト:*(全メトリック)

有効な値:詳細はメトリックセクションをご覧ください。

例: metrics=plays_requested,displays

いいえ

dimensions

ディメンション名のカンマ区切りリスト。結果は指定したディメンションでグループ化されます。ディメンションが指定されていない場合、全ディメンションのすべての値が返されます。

有効な値:詳細はディメンションセクションをご覧ください。一度に3つのディメンションまで指定できます。

デフォルト:なし

例: dimensions=country,region

いいえ

filters

指定したフィルター値で出力セットが絞り込まれます。
Note: 2フィルターまで、最大1年(366日)の日付範囲を設定できます。3フィルターでは、最大1か月(31日)の日付範囲を設定できます。

有効な値:有効なフィルター名やブール演算についてはフィルターをご覧ください。

  • filter_byの値はURLエンコードされている必要があります。
  • 実際のフィルターの値は一重引用符で囲む必要があります。

デフォルト:なし

例:
  • 国名オーストラリアでフィルタリング:filters=country=='AU'
  • 国名コロンビアでデバイスタイプをフィルタリング:filters=country==’CO’,device_type==’mobile’

いいえ

time_segment

ディメンションデータの時間ベースセグメントを指定します。time_segmentとデータ保持期間についての動作に関する考察をご覧ください。データのブロックを並べ替えます。

Note: 1週間は月曜日~日曜日と定義されます。
有効な値:  
  • month | week | day

デフォルト:なし

例: time_segment=day

いいえ

sort

並べ替え条件となるカンマ区切りメトリック名のリストです。複数のメトリックがある場合、それらはクエリに入れた順序で並べ替えられます。(そのメトリックデータがある場合)明示的に使用できる並べ替え可能なメトリック数には制限はありませんが、デフォルトでは2つに制限されています。

デフォルト:クエリ指定順で最初の2つのメトリック(データがあるという条件で)が並べ替えられます。並べ替え順のデフォルトは降順です。昇順にするには、対象のメトリック名の先頭に+のプレフィックス文字を付けます。

例:
  • 再生数、表示回数、ビデオ開始数を降順並べ替え:sort=plays_requested,displays,video_starts
  • ビデオ開始数を降順並べ替え:sort=+video_starts
Note:

並べ替えにsegment_watchedまたはpercentage_watchedを使用しないことをお勧めします。代わりにplays_requestedのような他のメトリックを使ってください。

さまざまなメトリック用に異なるソート動作が存在します。例えば、 segment_watchedやpercentage_watchedは並べ替えに(全配列の)文字列を使用し、数字の並び替えを使用しません。つまり、segment_watchedで並び替えた場合、結果は数字の順番では表示されません。segment_watchedの数が2番目の結果よりも低い結果が最初の結果として表示されることがあります(例、[99,…] , [999,...])。

一方、plays_requestedは数字の並び替えを使用しており、明白な結果が表示されます。

いいえ

limit

応答で返されるレコード数を制限します。最大数:10,000。

デフォルト:50

例: limit=100

いいえ

page

ページ数を示す整数です。下限値は0(ゼロ)です。

デフォルト:0

例:2ページ目:page=1

いいえ

time_segmentとデータ保持期間について

時間範囲はリクエストに対応する最小範囲まで自動的に拡張されます。例えば、開始日と終了日を今日にして、weektime_segmentを指定すると、指定された開始/終了日は(プロバイダーのタイムゾーン)現在の週をカバーするように変更されます。指定されたtime_segmentが存在しない場合、指定されたディメンションの総計が返されます。time_segmentまたは指定されたディメンションのどちらもないときは、時間範囲の総計が返されます。

この記事はお役にたちましたか?