認証が必要です
定義したフィルタとパラメータを使用して、検索トラフィック データをクエリします。このメソッドは、定義した行キー(ディメンション)でグループ化された 0 個以上の行を返します。1 日以上の期間を定義する必要があります。
日付がディメンションの 1 つである場合、データのない日は結果リストから除外されます。データがある日を確認するには、日付でグループ化されたフィルタを使用せずに、対象の期間でクエリを発行します。
結果はクリック数の降順で表示されます。2 つの行が同じクリック数を持つ場合、それらの行は任意の方法で並べ替えられます。
このメソッドを呼び出す方法については、Python のサンプルをご覧ください。
この API は Search Console の内部制限により制限されており、すべてのデータ行を返す保証ではなく、上位の行を返す保証はありません。
詳しくは、利用可能なデータ量の制限をご覧ください。
POST https://www.googleapis.com/webmasters/v3/sites/https%3A%2F%2Fwww.example.com%2F/searchAnalytics/query?key={MY_API_KEY} { "startDate": "2015-04-01", "endDate": "2015-05-01", "dimensions": ["country","device"] }
リクエスト
HTTP リクエスト
POST https://www.googleapis.com/webmasters/v3/sites/siteUrl/searchAnalytics/query
パラメータ
パラメータ名 | 値 | 説明 |
---|---|---|
パスパラメータ | ||
siteUrl |
string |
Search Console で定義されているプロパティの URL。例:
http://www.example.com/ (URL プレフィックス プロパティの場合)、sc-domain:example.com (ドメイン プロパティの場合)
|
承認
このリクエストは、少なくとも次のうち 1 つのスコープでの承認が必要です(認証と承認の詳細をご確認ください)。
範囲 |
---|
https://www.googleapis.com/auth/webmasters.readonly |
https://www.googleapis.com/auth/webmasters |
リクエスト本文
リクエストの本文には、以下の構造を使用してデータを指定してください。
{ "startDate": string, "endDate": string, "dimensions": [ string ], "type": string, "dimensionFilterGroups": [ { "groupType": string, "filters": [ { "dimension": string, "operator": string, "expression": string } ] } ], "aggregationType": string, "rowLimit": integer, "startRow": integer }
プロパティ名 | 値 | 説明 | メモ |
---|---|---|---|
startDate |
string |
[必須] リクエストする期間の開始日。YYYY-MM-DD 形式、PT 時間(UTC - 7:00/8:00)で表します。終了日以前の日付を指定する必要があります。この値は範囲内に含まれます。 | |
endDate |
string |
[必須] リクエストされた期間の終了日。YYYY-MM-DD 形式、PT 時間(UTC - 7:00/8:00)で表します。開始日と同じか、それより後の日付を指定してください。この値は範囲内に含まれます。 | |
dimensions[] |
list |
[省略可] 結果をグループ化する 0 個以上のディメンション。結果は、これらのディメンションを指定した順序でグループ化されます。dimensionFilterGroups[].filters[].dimension では「日付」だけでなく任意のディメンション名を使用できます。グループ化ディメンション値は結合され、結果行ごとに一意のキーが作成されます。ディメンションを指定しない場合、すべての値が 1 行にまとめられます。グループ化できるディメンションの数に制限はありませんが、同じディメンションを 2 回グループ化することはできません。例: [国、デバイス] | |
searchType |
string |
非推奨。代わりに type を使用してください
|
|
type |
string |
[省略可] 結果を次のタイプに絞り込みます。
|
|
dimensionFilterGroups[] |
list |
[省略可] ディメンションのグループ化値に適用する 0 個以上のフィルタ グループ。レスポンスで行を返すには、すべてのフィルタ グループが一致している必要があります。1 つのフィルタ グループ内で、すべてのフィルタを一致させるか、少なくとも 1 つ一致させるかを指定できます。 | |
dimensionFilterGroups[].groupType |
string |
このグループ内のすべてのフィルタが true(「and」)を返す必要があるか、または 1 つ以上のフィルタが true を返す必要がある(まだサポートされていません)。
有効な値は次のとおりです。
|
|
dimensionFilterGroups[].filters[] |
list |
[省略可] 行に対してテストする 0 個以上のフィルタ。各フィルタは、ディメンション名、演算子、値で構成されます。最大長は 4,096 文字です。例:country equals FRA query contains mobile use device notContains tablet |
|
dimensionFilterGroups[].filters[].dimension |
string |
このフィルタが適用されるディメンション。ディメンションでグループ化していない場合でも、ここに表示されるディメンションでフィルタできます。
有効な値は次のとおりです。
|
|
dimensionFilterGroups[].filters[].operator |
string |
[省略可] 指定した値が行のディメンション値と一致する(または一致しない)方法。
有効な値は次のとおりです。
|
|
dimensionFilterGroups[].filters[].expression |
string |
演算子に応じて、照合または除外するフィルタの値。 | |
aggregationType |
string |
[省略可] データの集計方法。プロパティごとに集計すると、同じプロパティのすべてのデータが集計されます。ページごとに集計すると、すべてのデータが正規 URI で集計されます。ページでフィルタまたはグループ化する場合は、[自動] を選択します。それ以外の場合は、データの計算方法に応じてプロパティまたはページごとに集計できます。サイト別とページ別のデータの計算方法の違いについては、ヘルプ ドキュメントをご覧ください。 注: ページでグループ化またはフィルタした場合、プロパティ別に集計することはできません。 auto 以外の値を指定すると、結果の集計型はリクエストされた型と一致します。また、無効な型をリクエストした場合、エラーが発生します。リクエストされた型が無効な場合、API では集計方法は変更されません。 有効な値は次のとおりです。
|
|
rowLimit |
integer |
[省略可。有効範囲は 1 ~ 25,000、デフォルトは 1,000] 返される行の最大数。結果をページ分割するには、startRow オフセットを使用します。 |
|
startRow |
integer |
[省略可、デフォルトは 0] レスポンスの最初の行のゼロベースのインデックス。ゼロまたは正の数を指定してください。startRow がクエリの結果の数を超えると、レスポンスは行が 0 の正常なレスポンスになります。 |
|
dataState |
string |
[省略可] 「all」(大文字と小文字を区別しない)の場合、データには最新のデータが含まれます。「final」(大文字と小文字を区別しない)の場合、またはこのパラメータを省略した場合、返されるデータには最終的なデータのみが含まれます。 |
レスポンス
結果は、リクエストで指定されたディメンションに従ってグループ化されます。同じディメンション値を持つすべての値は 1 行にグループ化されます。たとえば、「国」ディメンションでグループ化すると、「usa」のすべての結果はグループ化され、「mdv」のすべての結果はグループ化されます。国とデバイスでグループ化した場合は、「米国、タブレット」の検索結果はすべてグループ化され、「米国、モバイル」の検索結果はすべてグループ化されます。クリック数やインプレッション数などの詳しい計算方法や、その意味については、検索アナリティクス レポートのドキュメントをご覧ください。
結果はクリック数の降順で並べ替えられます。日付でグループ化した場合、結果は日付の昇順(古い順、新しい順)に並べ替えられます。2 つの行の間に同じ値がある場合、並べ替え順は任意です。
返される値の最大数については、リクエストの rowLimit プロパティをご覧ください。
{ "rows": [ { "keys": [ string ], "clicks": double, "impressions": double, "ctr": double, "position": double } ], "responseAggregationType": string }
プロパティ名 | 値 | 説明 | メモ |
---|---|---|---|
rows[] |
list |
クエリで指定された順序でキー値でグループ化された行のリスト。 | |
rows[].keys[] |
list |
リクエストのディメンションに応じてグループ化された、その行のディメンション値のリスト(リクエストで指定された順序)。 | |
rows[].clicks |
double |
行のクリック数。 | |
rows[].impressions |
double |
行のインプレッション数。 | |
rows[].ctr |
double |
行のクリック率(CTR)。値の範囲は 0 ~ 1.0 です。 | |
rows[].position |
double |
検索結果の平均掲載順位。 | |
responseAggregationType |
string |
結果の集計方法。サイト別とページ別のデータの計算方法の違いについては、ヘルプ ドキュメントをご覧ください。
有効な値は次のとおりです。
|
試してみよう:
以下の API Explorer を使用して、ライブデータに対してこのメソッドを呼び出し、レスポンスを確認してください。