Search Analytics: query

به مجوز نیاز دارد

داده‌های ترافیک جستجویتان را با فیلترها و پارامترهایی که تعریف می‌کنید پُرسمان کنید. این روش صفر یا چند ردیف را که براساس کلیدهای ردیف (ابعاد) تعریف‌شده توسط شما گروه‌بندی شده‌اند برمی‌گرداند. باید محدوده تاریخی یک یا چند روزه تعریف کنید.

وقتی تاریخ یکی از ابعاد باشد، هر روزی که داده نداشته باشد از فهرست نتایج حذف می‌شود. برای اینکه بدانید کدام روزها داده دارند، پُرسمانی بدون فیلترهای گروه‌بندی‌شده براساس تاریخ برای محدوده تاریخ موردنظر صادر کنید.

نتایج براساس تعداد کلیک به‌صورت نزولی مرتب شده‌اند. اگر دو ردیف تعداد کلیک یکسانی داشته باشند، به‌صورت دلخواه مرتب می‌شوند.

برای فراخوانی این روش، نمونه پایتون را ببینید.

این میانای برنامه‌سازی کاربردی با محدودیت‌های داخلی 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 نشانی وب دارایی همان‌طور که در «کنسول جستجو» تعریف شده است. مثال‌ها: http://www.example.com/ (برای خصوصیت پیشوند نشانی وب) یا sc-domain:example.com (برای خصوصیت دامنه)

صدور مجوز

این درخواست به مجوز با حداقل یکی از دامنه‌های زیر نیاز دارد (درباره اصالت‌سنجی و مجوز بیشتر بخوانید).

حوزه
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 (ساعت هماهنگ جهانی - 7:00/8:00). باید کمتر یا مساوی با تاریخ پایان باشد. این مقدار در محدوده گنجانده شده است.
endDate string [الزامی] تاریخ پایان محدوده تاریخ درخواستی، در قالب YYYY-MM-DD، در زمان PT (ساعت هماهنگ جهانی - 7:00/8:00). باید بزرگ‌تر یا مساوی تاریخ شروع باشد. این مقدار در محدوده گنجانده شده است.
dimensions[] list [اختیاری] صفر یا چند بُعد برای گروه‌بندی نتایج. نتایج به‌ترتیبی که این ابعاد را ارائه می‌دهید گروه‌بندی می‌شوند. می‌توانید از هر نام بُعدی در dimensionFilterGroups[].filters[].dimension و همچنین «تاریخ» و «ساعت» استفاده کنید. مقادیر بُعد گروه‌بندی ترکیب می‌شوند تا کلید یکتایی برای هر ردیف نتیجه ایجاد شود. اگر هیچ بُعدی مشخص نشده باشد، همه مقادیر در یک ردیف ترکیب خواهند شد. محدودیتی برای تعداد ابعادی که می‌توانید براساس آن‌ها گروه‌بندی کنید وجود ندارد، اما نمی‌توانید براساس یک بعد دو بار گروه‌بندی کنید. مثال: [کشور، دستگاه]
searchType string منسوخ شده است، درعوض از type استفاده کنید
type string [اختیاری] نتایج را براساس نوع زیر فیلتر کنید:
  • «discover»: نتایج «کاوش»
  • «googleNews»: نتایج از news.google.com و برنامه Google News در Android و iOS. نتایج برگه «اخبار» در «جستجوی Google» را شامل نمی‌شود.
  • «news»: نتایج جستجو از برگه «اخبار» در «جستجوی Google».
  • «image»: نتایج جستجو از برگه «تصویر» در «جستجوی Google».
  • «video»: نتایج جستجوی ویدیو
  • «web»: [پیش‌فرض] نتایج را در برگه ترکیبی («همه») در «جستجوی Google» فیلتر می‌کند. نتایج «یافته‌ها» یا Google News را شامل نمی‌شود.
  • «webMultimodal»: نتایج جستجو از «لنز Google»، «حلقه جستجو» در Android، و بارگذاری‌های تصویر در «جستجوی Google».
dimensionFilterGroups[] list [اختیاری] صفر یا چند گروه فیلتر برای اعمال کردن روی مقادیر گروه‌بندی بُعد. همه گروه‌های فیلتر باید مطابقت داشته باشند تا ردیفی در پاسخ برگردانده شود. در یک گروه فیلتر، می‌توانید مشخص کنید که همه فیلترها باید مطابقت داشته باشند یا حداقل یکی باید مطابقت داشته باشد.
dimensionFilterGroups[].groupType string اینکه آیا همه فیلترهای این گروه باید مقدار درست را برگردانند («و»)، یا یک یا چند فیلتر باید مقدار درست را برگردانند (هنوز پشتیبانی نمی‌شود).

مقادیر پذیرفتنی عبارت‌اند از:
  • «and»: همه فیلترهای گروه باید مقدار درست برگردانند تا گروه فیلتردرست باشد.
dimensionFilterGroups[].filters[] list [اختیاری] صفر یا چند فیلتر برای آزمایش دربرابر ردیف. هر فیلتر شامل نام بُعد، عملگر، و مقدار است. حداکثر طول ۴۰۹۶ نویسه. مثال‌ها:
country equals FRA
query contains mobile use
device notContains tablet
dimensionFilterGroups[].filters[].dimension string بُعدی که این فیلتر بر آن اعمال می‌شود. می‌توانید براساس هر بُعدی که در اینجا فهرست شده است فیلتر کنید، حتی اگر براساس آن بُعد گروه‌بندی نکنید.

مقادیر پذیرفتنی عبارت‌اند از:
  • «country»: فیلتر کردن براساس کشور مشخص‌شده، همان‌طور که با کد کشور ۳ حرفی (ISO 3166-1 alpha-3) مشخص شده است.
  • «device»: نتایج را براساس نوع دستگاه مشخص‌شده فیلتر می‌کند. مقادیر پشتیبانی‌شده:
    • رایانه
    • تلفن همراه
    • رایانه لوحی
  • «page»: فیلتر کردن براساس رشته URI مشخص‌شده.
  • «query»: فیلتر کردن براساس رشته پُرسمان مشخص‌شده.
  • «searchAppearance»: فیلتر کردن براساس ویژگی خاصی از نتیجه جستجو. برای دیدن فهرست مقادیر دردسترس، پُرسمانی را که براساس «searchAppearance» گروه‌بندی شده است اجرا کنید. فهرست کامل مقادیر و شرح‌ها در سند راهنما نیز دردسترس است.
  • «brandedClassification»: نتایج را براساس طبقه‌بندی پُرسمان نمانامی مشخص‌شده فیلتر می‌کند (فقط از عملگر «equals» پشتیبانی می‌شود). فیلتر کردن یا گروه‌بندی براساس «brandedClassification» را نمی‌توان با فیلتر «query» در یک درخواست ترکیب کرد. داده‌ها از ۲۱ فوریه ۲۰۲۶ دردسترس است و فقط برای دارایی‌های سطح بالا با حجم پرسمان و ظهور کافی (به اعلامیه پرسمان‌های نمانامی مراجعه کنید). مقادیر پشتیبانی‌شده:
    • نمانام‌دار
    • NON_BRANDED
dimensionFilterGroups[].filters[].operator string [اختیاری] مقدار مشخص‌شده شما چگونه باید با مقدار بُعد برای ردیف مطابقت داشته باشد (یا نداشته باشد).

مقادیر پذیرفتنی عبارت‌اند از:
  • «contains»: مقدار ردیف باید حاوی عبارت شما یا برابر با آن باشد (غیرحساس به حروف بزرگ و کوچک).
  • «equals»: [پیش‌فرض] عبارت شما باید دقیقاً با مقدار ردیف برابر باشد (برای ابعاد صفحه و پُرسمان، حروف‌حساس است).
  • «notContains»: مقدار ردیف نباید عبارت شما را به‌صورت رشته فرعی یا مطابقت کامل (غیرحساس به حروف بزرگ و کوچک) داشته باشد.
  • «notEquals»: عبارت شما نباید دقیقاً با مقدار ردیف برابر باشد (حروف‌حساس برای ابعاد صفحه و پُرسمان).
  • «includingRegex»: عبارت باقاعده نحو RE2 که باید مطابقت داشته باشد.
  • «excludingRegex»: عبارت باقاعده نحو RE2 که نباید مطابقت داشته باشد.
dimensionFilterGroups[].filters[].expression string مقدار فیلتر برای مطابقت یا مستثنی کردن، بسته به اپراتور.
dimensionFilterGroups[].filterLists[] list [اختیاری] صفر یا چند فیلتر بُعد چندمقداری برای آزمایش دربرابر ردیف. برخلاف filters[] که با یک مقدار واحد برای هر ورودی مطابقت دارد، filterLists[] امکان مطابقت با چندین مقدار دقیقاً منطبق را برای یک بُعد واحد در یک فیلتر فراهم می‌کند. اگر مقدار ردیف برای dimension مشخص‌شده با هریک از expressions ارائه‌شده برابر باشد، آن ردیف با فهرست فیلتر مطابقت دارد. توجه داشته باشید که یک درخواست نمی‌تواند به‌طور هم‌زمان در هر دو filters و filterLists براساس یک بُعد فیلتر شود.
dimensionFilterGroups[].filterLists[].dimension string [الزامی] بُعدی که این فهرست فیلتر بر آن اعمال می‌شود.

مقادیر پذیرفتنی عبارت‌اند از:
  • «country»: فیلتر کردن براساس کشورهای مشخص‌شده، بااستفاده از کدهای کشور ۳ حرفی (ISO 3166-1 alpha-3).
  • ‫«device»: فیلتر کردن براساس انواع دستگاه مشخص‌شده (DESKTOP، MOBILE، TABLET).
dimensionFilterGroups[].filterLists[].expressions[] list [الزامی] فهرست مقادیر (string) برای فیلتر کردن.
aggregationType string

[اختیاری] نحوه انبوهش داده‌ها. اگر براساس دارایی انبوهش شده باشد، همه داده‌های مربوط به همان دارایی انبوهش می‌شود؛ اگر براساس صفحه انبوهش شده باشد، همه داده‌ها براساس URI متعارف انبوهش می‌شود. اگر براساس صفحه فیلتر یا گروه‌بندی می‌کنید، auto را انتخاب کنید؛ درغیراین‌صورت می‌توانید براساس دارایی یا صفحه انبوهش کنید، بسته به اینکه می‌خواهید داده‌هایتان چگونه محاسبه شود؛ برای آشنایی با نحوه محاسبه متفاوت داده‌ها براساس سایت درمقابل صفحه، سند راهنما را ببینید.

توجه: اگر براساس صفحه گروه‌بندی یا فیلتر کنید، نمی‌توانید براساس دارایی تجمیع کنید.

اگر هر مقداری به‌غیراز auto را مشخص کنید، نوع انبوهش در نتیجه با نوع درخواستی مطابقت خواهد داشت، یا اگر نوع نامعتبری را درخواست کنید، خطا دریافت خواهید کرد. اگر نوع درخواست‌شده نامعتبر باشد، میانای برنامه‌سازی کاربردی هرگز نوع انبوهش شما را تغییر نخواهد داد.

مقادیر پذیرفتنی عبارت‌اند از:
  • «auto»: [پیش‌فرض] به سرویس اجازه می‌دهد نوع تجمیع مناسب را تعیین کند.
  • «byNewsShowcasePanel»: مقادیر تجمیعی براساس پانل «ویترین News». این باید در ترکیب با فیلتر NEWS_SHOWCASE searchAppearance و type=discover یا type=googleNews استفاده شود. اگر براساس صفحه گروه‌بندی کنید، براساس صفحه فیلتر کنید، یا به searchAppearance دیگری فیلتر کنید، نمی‌توانید براساس byNewsShowcasePanel انبوهش کنید.
  • ‫«byPage»: مقادیر را براساس URI انبوهش می‌کند.
  • «byProperty»: مقادیر را براساس دارایی تجمیع می‌کند. برای type=discover یا type=googleNews پشتیبانی نمی‌شود
rowLimit integer [اختیاری؛ محدوده معتبر ۱ تا ۲۵٬۰۰۰ است؛ پیش‌فرض ۱٬۰۰۰ است] حداکثر تعداد ردیف‌ها برای برگرداندن. برای ورق زدن نتایج، از افست startRow استفاده کنید.
startRow integer [اختیاری؛ پیش‌فرض ۰ است] نمایه مبتنی بر صفر ردیف اول در پاسخ. باید عدد غیرمنفی باشد. اگر startRow از تعداد نتایج پُرسمان فراتر رود، پاسخ موفقیت‌آمیز با صفر ردیف خواهد بود.
dataState string [اختیاری] اگر «همه» (غیرحساس به حروف بزرگ و کوچک) باشد، داده‌ها شامل داده‌های جدید خواهد بود. اگر «final» (غیرحساس به حروف بزرگ و کوچک) باشد یا اگر این پارامتر حذف شود، داده‌های برگردانده‌شده فقط شامل داده‌های نهایی‌شده خواهد بود. اگر «hourly_all» (غیرحساس به حروف بزرگ و کوچک) باشد، داده‌ها شامل تفکیک ساعتی خواهد بود. این نشان می‌دهد که داده‌های ساعتی شامل داده‌های جزئی است و باید هنگام گروه‌بندی براساس بُعد HOUR API استفاده شود.

پاسخ

نتایج براساس ابعاد مشخص‌شده در درخواست گروه‌بندی می‌شوند. همه مقادیر با مجموعه یکسانی از مقادیر بُعد در یک ردیف گروه‌بندی خواهند شد. برای مثال، اگر براساس بُعد کشور گروه‌بندی کنید، همه نتایج مربوط به «usa» باهم گروه‌بندی می‌شوند، همه نتایج مربوط به «mdv» باهم گروه‌بندی می‌شوند، و غیره. اگر براساس کشور و دستگاه گروه‌بندی کرده باشید، همه نتایج مربوط به «ایالات متحده، رایانه لوحی» گروه‌بندی می‌شود، همه نتایج مربوط به «ایالات متحده، تلفن همراه» گروه‌بندی می‌شود، و غیره. برای آشنایی با جزئیات نحوه محاسبه کلیک‌ها، ظهورها، و غیره و معنی آن‌ها، سند گزارش Search Analytics را ببینید.

نتایج براساس تعداد کلیک‌ها به‌ترتیب نزولی مرتب می‌شوند، مگراینکه براساس تاریخ گروه‌بندی کنید که دراین‌صورت نتایج براساس تاریخ به‌ترتیب صعودی مرتب می‌شوند (قدیمی‌ترین در ابتدا، جدیدترین در انتها). اگر دو ردیف باهم برابر باشند، ترتیب مرتب‌سازی اختیاری است.

برای اطلاع از حداکثر تعداد مقادیری که می‌توانند برگردانده شوند، ویژگی 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) برای ردیف. مقادیر از ۰ تا ۱٫۰ است و می‌تواند این دو عدد را نیز دربر بگیرد.
rows[].position double جایگاه میانگین در نتایج جستجو.
responseAggregationType string نحوه تجمیع نتایج. برای آشنایی با نحوه محاسبه متفاوت داده‌ها براساس سایت درمقابل صفحه،سند راهنما را ببینید.

مقادیر پذیرفتنی عبارت‌اند از:
  • «auto»
  • «byPage»: نتایج براساس صفحه تجمیع شده است.
  • «byProperty»: نتایج براساس دارایی تجمیع شده است.
metadata object

شیئی که ممکن است با نتایج پُرسمان شما برگردانده شود و زمینه‌ای درباره وضعیت داده‌ها ارائه دهد.

وقتی داده‌های اخیر را درخواست می‌کنید (بااستفاده از all یا hourly_all برای dataState)، برخی‌از ردیف‌های برگردانده‌شده ممکن است نشان‌دهنده داده‌های ناقص باشند، یعنی داده‌ها هنوز درحال جمع‌آوری و پردازش هستند. این شیء فراداده به شما کمک می‌کند دقیقاً زمان شروع و پایان آن را شناسایی کنید.

همه تاریخ‌ها و زمان‌های ارائه‌شده در این شیء در منطقه زمانی 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 ممکن است همچنان به‌طور قابل‌توجهی تغییر کنند.

امتحان کنید!

از «کاوشگر میاناهای برنامه‌سازی کاربردی» زیر برای فراخوانی این روش در داده‌های زنده و دیدن پاسخ استفاده کنید.