認証が必要です
定義したフィルタとパラメータを使用して、検索トラフィック データをクエリします。このメソッドは、定義した行キー(ディメンション)でグループ化された 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
}
],
"filterLists": [
{
"dimension": string,
"expressions": [
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 では、「date」や「hour」だけでなく、任意のディメンション名を使用できます。グループ化ディメンションの値が結合され、各結果行の一意のキーが作成されます。ディメンションが指定されていない場合、すべての値が 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 |
演算子に応じて、フィルタが一致または除外する値。 | |
dimensionFilterGroups[].filterLists[] |
list |
[省略可] 行に対してテストする 0 個以上の多値ディメンション フィルタ。エントリごとに 1 つの値に一致する filters[] とは異なり、filterLists[] では、1 つのフィルタで 1 つのディメンションに対して複数の完全一致値を照合できます。指定された dimension の値が、指定された expressions のいずれかと等しい場合、行はフィルタリストに一致します。1 つのリクエストで、filters と filterLists の両方で同じディメンションを同時にフィルタすることはできません。 |
|
dimensionFilterGroups[].filterLists[].dimension |
string |
[必須] このフィルタリストが適用されるディメンション。 有効な値は次のとおりです。
|
|
dimensionFilterGroups[].filterLists[].expressions[] |
list |
[必須] フィルタする値(string)のリスト。 |
|
aggregationType |
string |
[省略可] データの集計方法。プロパティごとに集計される場合は、同じプロパティのすべてのデータが集計されます。ページごとに集計される場合は、すべてのデータが正規 URI ごとに集計されます。ページでフィルタまたはグループ化する場合は、[自動] を選択します。それ以外の場合は、データの計算方法に応じて、プロパティごとまたはページごとに集計できます。サイトごととページごとのデータの計算方法の違いについては、ヘルプ ドキュメントをご覧ください。 注: ページでグループ化またはフィルタする場合、プロパティで集計することはできません。 auto 以外の値を指定すると、結果の集計タイプはリクエストされたタイプと一致します。無効なタイプをリクエストすると、エラーが発生します。リクエストされたタイプが無効な場合、API が集計タイプを変更することはありません。 有効な値は次のとおりです。
|
|
rowLimit |
integer |
[省略可。有効な範囲は 1 ~ 25,000。デフォルトは 1,000] 返される行の最大数。結果をページ分割するには、startRow オフセットを使用します。 |
|
startRow |
integer |
[省略可。デフォルトは 0] レスポンスの最初の行の 0 から始まるインデックス。ゼロまたは正の数を指定してください。startRow がクエリの結果数を超えると、レスポンスは 0 行の成功レスポンスになります。 |
|
dataState |
string |
[省略可] 「all」(大文字と小文字を区別しない)の場合、データには最新のデータが含まれます。 「final」(大文字と小文字を区別しない)の場合、またはこのパラメータを省略した場合、返されるデータには確定済みのデータのみが含まれます。 「hourly_all」(大文字と小文字を区別しない)の場合、データには時間別の内訳が含まれます。これにより、時間単位のデータに部分的なデータが含まれていることが示されます。このフィールドは、HOUR API ディメンションでグループ化する場合に使用する必要があります。 |
レスポンス
結果は、リクエストで指定されたディメンションに従ってグループ化されます。同じディメンション値のセットを持つすべての値が 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 |
結果の集計方法。サイトごととページごとのデータの計算方法の違いについては、ヘルプ ドキュメントをご覧ください。
有効な値は次のとおりです。
|
|
metadata |
object |
クエリ結果とともに返される可能性のあるオブジェクト。データの状態に関するコンテキストを提供します。 最近のデータをリクエストすると( このオブジェクトで指定されるすべての日時は、 このオブジェクト内で返される特定のフィールドは、リクエストでデータをどのようにグループ化したかによって異なります。
|
試してみよう:
以下の API Explorer を使用して、ライブデータに対してこのメソッドを呼び出し、レスポンスを確認します。