認証が必要です
定義したフィルタとパラメータを使用して、検索トラフィック データをクエリします。このメソッドは、定義した行キー(ディメンション)でグループ化された 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 |
[必須] リクエストした期間の開始日(太平洋時間(UTC - 7:00/8:00)の YYYY-MM-DD 形式)。終了日以下の日付を指定してください。この値は範囲に含まれます。 | |
endDate |
string |
[必須] リクエストされた期間の終了日(YYYY-MM-DD 形式、太平洋時間(UTC - 7:00/8:00))。開始日以降の日付を指定してください。この値は範囲に含まれます。 | |
dimensions[] |
list |
[省略可] 結果をグループ化するディメンションを 0 個以上指定します。結果は、指定したディメンションの順序でグループ化されます。dimensionFilterGroups[].filters[].dimension では、任意のディメンション名と「date」を使用できます。グループ化ディメンションの値が結合され、結果の行ごとに一意のキーが作成されます。ディメンションが指定されていない場合、すべての値が 1 つの行に結合されます。グループ化できるディメンションの数に上限はありませんが、同じディメンションで 2 回グループ化することはできません。例: [country, device] | |
searchType |
string |
非推奨。代わりに type を使用してください。
|
|
type |
string |
[省略可] 結果を次のタイプにフィルタします。
|
|
dimensionFilterGroups[] |
list |
[省略可] ディメンションのグループ化値に適用するフィルタのグループを 1 つ以上指定します。レスポンスで行が返されるためには、すべてのフィルタ グループが一致している必要があります。1 つのフィルタグループ内で、すべてのフィルタが一致する必要があるか、少なくとも 1 つが一致する必要があるかを指定できます。 | |
dimensionFilterGroups[].groupType |
string |
このグループ内のすべてのフィルタが true(および)を返すか、1 つ以上のフィルタが true を返す必要があるか(まだサポートされていません)を指定します。
有効な値は次のとおりです。
|
|
dimensionFilterGroups[].filters[] |
list |
[省略可] 行に対してテストするフィルタ。各フィルタは、ディメンション名、演算子、値で構成されます。最大長は 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] レスポンスの最初の行のゼロベースのインデックス。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 を使用して、ライブデータに対してこのメソッドを呼び出し、レスポンスを確認します。