認証が必要です
自分で定義したフィルタとパラメータを使用して、検索トラフィック データをクエリします。このメソッドは、定義した行キー(ディメンション)でグループ化された 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 |
[省略可] ディメンションのグループ化値に適用する任意のフィルタ グループ(複数可)。レスポンスで行が返されるためには、すべてのフィルタ グループが一致している必要があります。1 つのフィルタ グループ内で、すべてのフィルタに一致するか、少なくとも 1 つ一致する必要があるかを指定できます。 | |
dimensionFilterGroups[].groupType |
string |
このグループ内のすべてのフィルタが true(「and」)を返す必要があるか、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 がクエリの結果の数を超えると、レスポンスは行ゼロの正常なレスポンスになります。 |
|
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 を使用して、ライブデータに対してこのメソッドを呼び出し、レスポンスを確認してください。