Search Analytics: query

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

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

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

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

برای فراخوانی این متد به نمونه پایتون مراجعه کنید.

این API با محدودیت‌های داخلی کنسول جستجو محدود شده است و تضمین نمی‌کند که تمام ردیف‌های داده را برگرداند، بلکه ردیف‌های برتر را برمی‌گرداند.

محدودیت‌های میزان داده‌های موجود را ببینید .

مثال 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 آدرس اینترنتی (URL) ملک مورد نظر همانطور که در کنسول جستجو تعریف شده است. مثال‌ها: http://www.example.com/ (برای ملک با پیشوند URL) یا 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
        }
      ]
    }
  ],
  "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 [ اختیاری ] صفر یا چند بُعد برای گروه‌بندی نتایج بر اساس. نتایج به ترتیبی که این ابعاد را ارائه می‌دهید گروه‌بندی می‌شوند. می‌توانید از هر نام بُعدی در dimensionFilterGroups[].filters[].dimension و همچنین "date" و "hour". مقادیر بُعد گروه‌بندی برای ایجاد یک کلید منحصر به فرد برای هر ردیف نتیجه ترکیب می‌شوند. اگر هیچ بُعدی مشخص نشود، تمام مقادیر در یک ردیف ترکیب می‌شوند. هیچ محدودیتی برای تعداد بُعدهایی که می‌توانید بر اساس آنها گروه‌بندی کنید وجود ندارد، اما نمی‌توانید دو بار بر اساس یک بُعد گروه‌بندی کنید. مثال: [country, device]
searchType string منسوخ شده، به جای آن type استفاده کنید
type string [ اختیاری ] نتایج را به نوع زیر فیلتر کنید:
  • « discover »: کشف نتایج
  • « googleNews »: نتایج حاصل از news.google.com و برنامه Google News در اندروید و iOS. شامل نتایج برگه «اخبار» در جستجوی گوگل نمی‌شود.
  • « news »: نتایج جستجو از برگه «اخبار» در جستجوی گوگل.
  • « image »: نتایج جستجو از برگه «تصویر» در جستجوی گوگل.
  • « video »: نتایج جستجوی ویدئو
  • « web »: [ پیش‌فرض ] نتایج را در تب ترکیبی («همه») در جستجوی گوگل فیلتر می‌کند. شامل نتایج Discover یا Google News نمی‌شود.
dimensionFilterGroups[] list [ اختیاری ] صفر یا چند گروه فیلتر برای اعمال بر مقادیر گروه‌بندی بُعد. برای اینکه یک ردیف در پاسخ برگردانده شود، همه گروه‌های فیلتر باید مطابقت داشته باشند. در یک گروه فیلتر واحد، می‌توانید مشخص کنید که آیا همه فیلترها باید مطابقت داشته باشند یا حداقل یکی از آنها باید مطابقت داشته باشد.
dimensionFilterGroups[]. groupType string اینکه آیا همه فیلترهای این گروه باید مقدار درست ("و") را برگردانند، یا یک یا چند فیلتر باید مقدار درست ( هنوز پشتیبانی نمی‌شود) را برگردانند.

مقادیر قابل قبول عبارتند از:
  • " and ": همه فیلترهای موجود در گروه باید برای گروه فیلتر t مقدار true را برگردانند. ای. صادق باش.
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» اجرا کنید. لیست کامل مقادیر و توضیحات نیز در مستندات راهنما موجود است.
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 تجمیع می‌کند. این باید در ترکیب با فیلتر NEWS_SHOWCASE searchAppearance و یا type=discover یا type=googleNews استفاده شود. اگر بر اساس صفحه گروه‌بندی کنید، بر اساس صفحه فیلتر کنید یا به searchAppearance دیگری فیلتر کنید، نمی‌توانید بر اساس byNewsShowcasePanel تجمیع کنید.
  • « byPage »: مقادیر را بر اساس URI جمع‌آوری می‌کند.
  • « byProperty »: مقادیر را بر اساس ویژگی تجمیع می‌کند. برای type=discover یا type=googleNews پشتیبانی نمی‌شود.
rowLimit integer [ اختیاری؛ محدوده معتبر ۱ تا ۲۵۰۰۰ است؛ پیش‌فرض ۱۰۰۰ است ] حداکثر تعداد ردیف‌هایی که باید برگردانده شوند. برای پیمایش نتایج، از آفست startRow استفاده کنید.
startRow integer [ اختیاری؛ پیش‌فرض ۰ است ] اندیس مبتنی بر صفر اولین ردیف در پاسخ. باید یک عدد غیر منفی باشد. اگر startRow از تعداد نتایج برای پرس‌وجو بیشتر شود، پاسخ یک پاسخ موفق با صفر ردیف خواهد بود.
dataState string [ اختیاری ] اگر "all" (غیرحساس به حروف بزرگ و کوچک) باشد، داده‌ها شامل داده‌های جدید نیز خواهند بود. اگر "final" (غیرحساس به حروف بزرگ و کوچک) باشد یا اگر این پارامتر حذف شود، داده‌های برگردانده شده فقط شامل داده‌های نهایی شده خواهند بود. اگر "hourly_all" (غیرحساس به حروف بزرگ و کوچک) باشد، داده‌ها شامل تفکیک ساعتی نیز خواهند بود. این نشان می‌دهد که داده‌های ساعتی شامل داده‌های جزئی نیز می‌شوند و باید هنگام گروه‌بندی بر اساس بُعد HOUR API استفاده شوند.

پاسخ

نتایج بر اساس ابعاد مشخص شده در درخواست گروه‌بندی می‌شوند. تمام مقادیری که مجموعه مقادیر ابعاد یکسانی دارند، در یک ردیف گروه‌بندی می‌شوند. برای مثال، اگر بر اساس بعد کشور گروه‌بندی کنید، تمام نتایج مربوط به "usa" با هم گروه‌بندی می‌شوند، تمام نتایج مربوط به "mdv" با هم گروه‌بندی می‌شوند و به همین ترتیب ادامه می‌یابد. اگر بر اساس کشور و دستگاه گروه‌بندی کنید، تمام نتایج مربوط به "usa, tablet" گروه‌بندی می‌شوند، تمام نتایج مربوط به "usa, mobile" گروه‌بندی می‌شوند و به همین ترتیب ادامه می‌یابد. برای آشنایی با جزئیات نحوه محاسبه کلیک‌ها، نمایش‌ها و غیره و معنای آنها، به مستندات گزارش 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) برای هر ردیف. مقادیر از 0 تا 1.0 متغیر است.
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 ممکن است همچنان به طور قابل توجهی تغییر کنند.

امتحانش کن!

از API Explorer زیر برای فراخوانی این متد روی داده‌های زنده و مشاهده پاسخ استفاده کنید.