Search Analytics: query

認証が必要です

定義したフィルタとパラメータを使用して、検索トラフィック データのクエリを実行できます。このメソッドは、定義した行キー（ディメンション）でグループ化された 0 個以上の行を返します。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 と「日付」では、任意のディメンション名を使用できます。グループ化ディメンションの値は組み合わされて、結果の行ごとに一意のキーが作成されます。ディメンションを指定しないと、すべての値が 1 行にまとめられます。グループ化できるディメンションの数に制限はありませんが、同じディメンションで 2 回グループ化することはできません。例: [国、デバイス]
searchType string 非推奨。代わりに type を使用してください。
type string [省略可] 結果を次のタイプにフィルタします。
  • 「discover」: 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": [デフォルト] 適切な集約タイプはサービスが決定します。
  • "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」（大文字と小文字を区別しない）の場合、データには最新のデータが含まれます。「最終」（大文字と小文字を区別しない）を指定するか、このパラメータを省略した場合、返されるデータにはファイナライズされたデータのみが含まれます。

レスポンス

結果は、リクエストで指定されたディメンションに従ってグループ化されます。同じディメンション値のセットを持つ値はすべて、1 行にグループ化されます。たとえば、国のディメンションでグループ化すると、「usa」のすべての結果がグループ化され、「mdv」のすべての結果はグループ化されます。国やデバイス別にグループ化した場合、「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」: 結果はプロパティごとに集計されました。

試してみよう:

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