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
        }
      ],
      "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 [省略可] 結果を次のタイプにフィルタします。
  • 「discover」: Discover の結果
  • 「googleNews」: news.google.com と Google ニュース アプリ(Android と iOS)からの結果。Google 検索の [ニュース] タブの結果は含まれません。
  • 「news」: Google 検索の [ニュース] タブの検索結果。
  • 「image」: Google 検索の [画像] タブの検索結果。
  • 「video」: 動画の検索結果
  • 「web」: [デフォルト] Google 検索の統合された [すべて] タブに検索結果をフィルタします。Discover や Google ニュースの結果は含まれません。
  • 「webMultimodal」: Google レンズ、Android の「かこって検索」、Google 検索での画像アップロードによる検索結果。
dimensionFilterGroups[] list [省略可] ディメンション グループの値に適用する 0 個以上のフィルタ グループ。レスポンスで行が返されるには、すべてのフィルタ グループが一致する必要があります。1 つのフィルタ グループ内で、すべてのフィルタが一致する必要があるか、少なくとも 1 つが一致する必要があるかを指定できます。
dimensionFilterGroups[].groupType string このグループのすべてのフィルタが true を返す必要があるか(「and」)、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」でグループ化されたクエリを実行します。 値と説明の完全なリストは、ヘルプ ドキュメントでも確認できます。
  • 「brandedClassification」: 指定されたブランドクエリ分類に対して結果をフィルタします(「equals」演算子のみがサポートされています)。「brandedClassification」によるフィルタリングまたはグループ化を、同じリクエスト内の「query」フィルタと組み合わせることはできません。データは 2026 年 2 月 21 日以降、クエリ数とインプレッション数が十分な最上位プロパティでのみ利用できます(ブランドクエリに関するお知らせをご覧ください)。サポートされている値:
    • ブランド
    • NON_BRANDED
dimensionFilterGroups[].filters[].operator string [省略可] 指定した値が、行のディメンション値とどのように一致する(または一致しない)必要があるか。

有効な値は次のとおりです。
  • 「contains」: 行の値に、指定した式が含まれているか、指定した式と一致している必要があります(大文字と小文字を区別しません)。
  • 「equals」: [デフォルト] 式は行の値と完全に一致する必要があります(ページとクエリのディメンションでは大文字と小文字が区別されます)。
  • 「notContains」: 行の値に、部分文字列または(大文字と小文字を区別しない)完全一致として式が含まれていてはなりません。
  • 「notEquals」: 式は行の値と完全に一致してはなりません(ページとクエリのディメンションでは大文字と小文字が区別されます)。
  • "includingRegex": 一致する必要がある RE2 構文の正規表現。
  • "excludingRegex": 一致してはならない RE2 構文の正規表現。
dimensionFilterGroups[].filters[].expression string 演算子に応じて、フィルタが一致または除外する値。
dimensionFilterGroups[].filterLists[] list [省略可] 行に対してテストする 0 個以上の多値ディメンション フィルタ。エントリごとに 1 つの値に一致する filters[] とは異なり、filterLists[] では、1 つのフィルタで 1 つのディメンションに対して複数の完全一致値を照合できます。指定された dimension の値が、指定された expressions のいずれかと等しい場合、行はフィルタリストに一致します。1 つのリクエストで、filters と filterLists の両方で同じディメンションを同時にフィルタすることはできません。
dimensionFilterGroups[].filterLists[].dimension string [必須] このフィルタリストが適用されるディメンション。

有効な値は次のとおりです。
  • "country": 3 文字の国コード(ISO 3166-1 alpha-3)を使用して、指定した国でフィルタします。
  • "device": 指定したデバイスタイプ(DESKTOP、MOBILE、TABLET)でフィルタします。
dimensionFilterGroups[].filterLists[].expressions[] list [必須] フィルタする値(string)のリスト。
aggregationType string

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

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

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

有効な値は次のとおりです。
  • "auto": [デフォルト] 適切な集計タイプをサービスに決定させます。
  • 「byNewsShowcasePanel」: ニュース ショーケース パネルごとに値を集計します。これは、NEWS_SHOWCASE searchAppearance フィルタと、type=discover または type=googleNews と組み合わせて使用する必要があります。ページでグループ化、ページでフィルタ、または別の searchAppearance でフィルタする場合、byNewsShowcasePanel で集計することはできません。
  • "byPage": URI ごとに値を集計します。
  • 「byProperty」: プロパティごとに値を集計します。type=discover または type=googleNews ではサポートされていません
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 結果の集計方法。サイトごととページごとのデータの計算方法の違いについては、ヘルプ ドキュメントをご覧ください。

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

クエリ結果とともに返される可能性のあるオブジェクト。データの状態に関するコンテキストを提供します。

最近のデータをリクエストすると(dataState に all または hourly_all を使用)、返される行の一部が不完全なデータを表すことがあります。これは、データがまだ収集および処理中であることを意味します。このメタデータ オブジェクトは、この開始と終了の正確なタイミングを特定するのに役立ちます。

このオブジェクトで指定されるすべての日時は、America/Los_Angeles タイムゾーンです。

このオブジェクト内で返される特定のフィールドは、リクエストでデータをどのようにグループ化したかによって異なります。

  • first_incomplete_date(string): データの収集と処理がまだ行われている最初の日付。YYYY-MM-DD 形式(ISO-8601 拡張ローカル日付形式)で表示されます。

    このフィールドは、リクエストの dataState が all で、データが date でグループ化され、リクエストされた期間に不完全なデータポイントが含まれている場合にのみ入力されます。

    first_incomplete_date 以降のすべての値は、今後も大きく変化する可能性があります。

  • first_incomplete_hour(string): データの収集と処理がまだ行われている最初の時間。YYYY-MM-DDThh:mm:ss[+|-]hh:mm 形式(ISO-8601 拡張オフセット日時形式)で表示されます。

    このフィールドは、リクエストの dataState が hourly_all で、データが hour でグループ化され、リクエストされた期間に不完全なデータポイントが含まれている場合にのみ入力されます。

    first_incomplete_hour 以降のすべての値は、今後も大きく変化する可能性があります。

試してみよう:

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