認証が必要です
定義したフィルタとパラメータを使用して、検索トラフィック データをクエリします。このメソッドは、定義した行キー(ディメンション)でグループ化された 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 がクエリの結果の数を超えると、行のない成功のレスポンスが返されます。 |
|
dataState |
string |
[省略可] 「すべて」(大文字と小文字を区別しない)の場合、データには最新のデータが含まれます。「final」(大文字と小文字を区別しない)またはこのパラメータを省略した場合、返されるデータには最終的なデータのみが含まれます。 |
レスポンス
結果は、リクエストで指定されたディメンションに応じてグループ化されます。同じディメンション値のセットを持つすべての値は、1 つの行にグループ化されます。たとえば、国のディメンションでグループ化すると、「usa」のすべての結果はグループ化され、「mdv」のすべての結果はグループ化されます。国とデバイスでグループ化した場合、「usa,タブレット」の検索結果はすべてグループ化され、「usa, mobile」の検索結果はすべてグループ化されます。クリック数やインプレッション数などの具体的な計算方法やその意味については、検索アナリティクス レポートのドキュメントをご覧ください。
結果はクリック数の降順で並べ替えられます。ただし、日付でグループ化した場合、結果は日付の昇順(古い順、新しい順)で並べ替えられます。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 を使用して、ライブデータでこのメソッドを呼び出し、レスポンスを確認してください。