Search Analytics: query

認証が必要です

定義したフィルタとパラメータを使用して、検索トラフィック データをクエリします。このメソッドは、定義した行キー(ディメンション)ごとにグループ化された 0 個以上の行を返します。1 日以上の期間を定義する必要があります。

日付がディメンションの 1 つである場合、データのない日は結果リストから除外されます。データのある期間を調べるには、目的の期間について、日付でグループ化されたフィルタのないクエリを発行します。

結果はクリック数の降順で並べ替えられます。クリック数が同じである 2 つの行は、任意の方法で並べ替えられます。

このメソッドを呼び出す方法については、Python サンプルをご覧ください。

この API は Search Console の内部的な制限に制約されており、すべてのデータ行ではなく、一番上の行を返す保証はありません。

利用可能なデータ量の上限を確認する

JSON POST の例:
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 の任意のディメンション名と「date」を使用できます。グループ化ディメンションの値を組み合わせることで、結果行ごとに一意のキーが作成されます。ディメンションを指定しない場合、すべての値が 1 行に結合されます。グループ化できるディメンションの数に制限はありませんが、同じディメンションで 2 回グループ化することはできません。例: [国、デバイス]
searchType string 非推奨。代わりに type を使用してください
type string [省略可] 結果を次のタイプでフィルタします。
  • discover」: 結果を見つける
  • googleNews」: news.google.com と、Android / iOS 版 Google ニュースアプリの検索結果。Google 検索の [ニュース] タブの検索結果は含まれません。
  • news」: Google 検索の [ニュース] タブの検索結果。
  • image」: Google 検索の [画像] タブの検索結果。
  • video」: 動画の検索結果
  • "web": [デフォルト] Google 検索の [結合] タブ([すべて] タブ)に結果をフィルタします。Discover や Google ニュースの検索結果は含まれません。
dimensionFilterGroups[] list [省略可] ディメンション グループの値に適用する 0 個以上のフィルタ グループ。レスポンスで行が返されるためには、すべてのフィルタ グループが一致する必要があります。1 つのフィルタ グループ内で、すべてのフィルタが一致するか、少なくとも 1 つのフィルタが一致する必要があるかを指定できます。
dimensionFilterGroups[].groupType string このグループ内のすべてのフィルタで true(および)を返す必要があるか、1 つ以上の true(まだサポートされていません)を返す必要があるかを示します。

有効な値は次のとおりです。
  • "and": フィルタ グループが true の場合、グループ内のすべてのフィルタが true を返す必要があります。
dimensionFilterGroups[].filters[] list [省略可] 行に対してテストする 0 個以上のフィルタ。各フィルタは、ディメンション名、演算子、値で構成されます。最大 4,096 文字です。例:
country equals FRA
query contains mobile use
device notContains tablet
dimensionFilterGroups[].filters[].dimension string このフィルタが適用されるディメンションです。このディメンションでグループ化していない場合でも、ここに表示されているディメンションでフィルタできます。

有効な値は次のとおりです。
  • country: 3 文字の国コード(ISO 3166-1 alpha-3)で指定された国を基準にフィルタします。
  • "device": 指定したデバイスタイプを基準に結果をフィルタします。サポートされている値:
    • パソコン
    • モバイル
    • タブレット
  • "page": 指定した URI 文字列をフィルタします。
  • query: 指定したクエリ文字列でフィルタします。
  • "searchAppearance": 特定の検索結果特徴でフィルタします。使用可能な値のリストを表示するには、searchAppearance でグループ化されたクエリを実行します。
dimensionFilterGroups[].filters[].operator string [省略可] 指定した値が行のディメンション値と一致する必要がある(または一致しない)場合。

有効な値は次のとおりです。
  • "contains": 行の値には、式(大文字と小文字を区別しない)が含まれている必要があります。
  • "equals": デフォルト] 式は行の値と完全に一致している必要があります(ページとクエリのディメンションでは大文字と小文字が区別されます)。
  • notContains : 行の値に、部分文字列または(大文字と小文字の区別のない)完全一致として式を含めることはできません。
  • "notEquals": 式は行の値とまったく同じにしないでください(ページとクエリのディメンションでは大文字と小文字が区別されます)。
  • "includingRegex": 一致する必要がある RE2 構文の正規表現。
  • "excludingRegex": 一致してはならない RE2 構文の正規表現。
dimensionFilterGroups[].filters[].expression string 演算子に応じて一致または除外するフィルタの値。
aggregationType string

[省略可] データの集計方法。プロパティごとに集計される場合、同じプロパティのすべてのデータが集計されます(ページごとに集計される場合、すべてのデータは正規 URI によって集計されます)。ページごとにフィルタまたはグループ化する場合は自動を選択します。それ以外の場合は、データの計算方法に応じて、プロパティまたはページごとに集計できます。サイトごとにデータの計算方法がページごとに異なる方法については、ヘルプ ドキュメントをご覧ください。

注: ページでグループ化またはフィルタリングした場合、プロパティで集計することはできません。

auto 以外の値を指定すると、結果の集計タイプがリクエストされた型と一致するか、または無効な型をリクエストするとエラーが発生します。リクエストされたタイプが無効な場合、API は集計タイプを変更しません。

有効な値は次のとおりです。
  • "auto": [デフォルト] サービスで適切な集計方法を決定します。
  • "byPage": URI で値を集計します。
  • "byProperty": プロパティごとに値を集計します。type=discovertype=googleNews はサポート対象外
rowLimit integer [省略可。有効な範囲は 1 ~ 25,000 行。デフォルトは 1,000 行です] 返される最大行数。結果のページ分割を行うには、startRow オフセットを使用します。
startRow integer [省略可。デフォルトは 0] レスポンスの最初の行のゼロベースのインデックス。0 または正の数を指定してください。startRow がクエリの結果の数を超えると、レスポンスは成功し、0 行が返されます。
dataState string [省略可] すべて(大文字と小文字を区別しない)で、最新のデータが含まれます。「final」(大文字と小文字を区別しない)またはこのパラメータを省略すると、返されるデータにはファイナライズされたデータのみが含まれます。

レスポンス

結果は、リクエストで指定されたディメンションに従ってグループ化されます。同じディメンション値のセットを持つすべての値は 1 行にグループ化されます。たとえば、国のディメンションでグループ化すると、「usa」のすべての結果が「goether」にグループ化され、「mdv」のすべての結果が「グループ化」されます。国やデバイス別にグループ化すると、「usa、タブレット」のすべての結果がグループ化され、「usa、モバイル」のすべての結果がグループ化されます。クリック数、インプレッション数などの計算方法の詳細については、検索アナリティクス レポートのドキュメントをご覧ください。

結果は、日付の順(古い順、古い順)にクリック数の順に降順で並べ替えられます。2 行が互いに同じである場合、並べ替え順序は任意です。

返されることができる値の最大数については、リクエストの rowLimit プロパティをご覧ください。

{
  "rows": [
    {
      "keys": [
        string
      ],
      "clicks": double,
      "impressions": double,
      "ctr": double,
      "position": double
    }
  ],
  "responseAggregationType": string
}
プロパティ名 説明 備考
rows[] list クエリで指定された順序で Key-Value でグループ化された行のリスト。
rows[].keys[] list その行のディメンション値のリスト。リクエストで指定される順序で、リクエスト内のディメンションに応じてグループ化されます。
rows[].clicks double その行のクリック数。
rows[].impressions double その行のインプレッション数。
rows[].ctr double その行のクリック率(CTR)。値の範囲は 0 ~ 1.0 です。
rows[].position double 検索結果での平均掲載順位。
responseAggregationType string 結果の集計方法。サイトとページごとのデータの計算方法の違いについて詳しくは、ヘルプ ドキュメントをご覧ください。

有効な値は次のとおりです。
  • auto
  • byPage」: 結果はページごとに集計されました。
  • "byProperty": 結果はプロパティごとに集計されます。

実習

以下の API Explorer を使用して、ライブデータでこのメソッドを呼び出し、レスポンスを確認します。