このページは Cloud Translation API によって翻訳されました。

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 形式で、太平洋時間（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 回グループ化することはできません。例: [country, device]
`searchType`	`string`	非推奨。代わりに `type` を使用してください
`type`	`string`	[省略可] 結果を次のタイプにフィルタします。 "`discover`": Discover の結果「`googleNews`」: news.google.com と Google ニュースアプリ（Android と iOS）からの結果。Google 検索の [ニュース] タブの検索結果は含まれません。「`news`」: Google 検索の [ニュース] タブの検索結果。「`image`」: Google 検索の [画像] タブの検索結果。「`video`」: 動画の検索結果「`web`」: [デフォルト] Google 検索の [すべて] タブに検索結果をフィルタします。Discover や Google ニュースの結果は含まれません。
`dimensionFilterGroups[]`	`list`	[省略可] ディメンショングループ化値に適用するフィルタのグループ。0 個以上指定できます。レスポンスで行を返すには、すべてのフィルタグループが一致する必要があります。1 つのフィルタグループ内で、すべてのフィルタが一致する必要があるか、少なくとも 1 つが一致する必要があるかを指定できます。
`dimensionFilterGroups[].groupType`	`string`	このグループのすべてのフィルタが true を返す必要があるか（「and」）、1 つ以上のフィルタが true を返す必要があるか（まだサポートされていません）。有効な値は次のとおりです。「`and`」: フィルタグループ t が 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`」: 指定されたデバイスタイプに対して結果をフィルタします。サポートされている値: DESKTOP モバイル TABLET 「`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`」: [デフォルト] サービスが適切な集計タイプを決定します。 "`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` がクエリの結果数を超えている場合、レスポンスは行数がゼロの成功レスポンスになります。
`dataState`	`string`	[省略可] 「all」（大文字と小文字を区別しない）の場合、データには最新のデータが含まれます。「final」（大文字と小文字を区別しない）の場合、またはこのパラメータが省略されている場合、返されるデータには確定したデータのみが含まれます。「hourly_all」（大文字と小文字を区別しない）の場合、データには時間別内訳が含まれます。これにより、時間単位のデータに部分的なデータが含まれていることが示されます。このデータは、HOUR API ディメンションでグループ化するときに使用する必要があります。

レスポンス

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

結果はクリック数の降順で並べ替えられます。ただし、日付でグループ化した場合、結果は日付の昇順（古い順）で並べ替えられます。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 を使用し、ライブデータに対してこのメソッドを呼び出して、レスポンスを確認してみましょう。

Search Analytics: query コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。