Search Analytics: query

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

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

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

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

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

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 URL ویژگی همانطور که در کنسول جستجو تعریف شده است. مثال‌ها: http://www.example.com/ (برای یک ویژگی URL-prefix) یا sc-domain:example.com (برای یک ویژگی Domain)

مجوز

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

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

مقادیر قابل قبول عبارتند از:
  • " and ": همه فیلترهای گروه باید برای گروه فیلتر t برگردند o درست باشد
dimensionFilterGroups[]. filters[] list [ اختیاری ] صفر یا چند فیلتر برای آزمایش در برابر ردیف. هر فیلتر از یک نام بعد، یک عملگر و یک مقدار تشکیل شده است. حداکثر طول 4096 کاراکتر. مثال:
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 . این باید در ترکیب با NEWS_SHOWCASE searchAppearance فیلتر و یا type=discover یا type=googleNews استفاده شود. اگر بر اساس صفحه گروه بندی کنید، بر اساس صفحه فیلتر کنید، یا به searchAppearance دیگری فیلتر کنید، نمی توانید توسط byNewsShowcasePanel جمع آوری کنید.
  • " byPage ": مقادیر را بر اساس URI جمع کنید.
  • " byProperty ": مقادیر را بر اساس ویژگی جمع می کند. برای type=discover یا type=googleNews پشتیبانی نمی شود
rowLimit integer [ اختیاری؛ محدوده معتبر 1-25000 است. پیش‌فرض 1000 است ] حداکثر تعداد ردیف‌هایی که باید برگردانده شوند. برای صفحه بندی نتایج، از startRow offset استفاده کنید.
startRow integer [ اختیاری؛ پیش فرض 0 ] شاخص مبتنی بر صفر ردیف اول در پاسخ است . باید عددی غیر منفی باشد. اگر startRow از تعداد نتایج پرس و جو بیشتر شود، پاسخ یک پاسخ موفق با ردیف صفر خواهد بود.
dataState string [ اختیاری ] اگر "همه" (بدون حساسیت به حروف بزرگ)، داده‌ها شامل داده‌های تازه می‌شوند. اگر "نهایی" (بدون حساس به حروف بزرگ) یا اگر این پارامتر حذف شود، داده های برگشتی فقط شامل داده های نهایی می شود.

واکنش

نتایج بر اساس ابعاد مشخص شده در درخواست گروه بندی می شوند. همه مقادیر با مجموعه ای از مقادیر ابعاد یکسان در یک ردیف گروه بندی می شوند. به عنوان مثال، اگر بر اساس بعد کشور گروه بندی کنید، همه نتایج برای "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 ": نتایج بر اساس دارایی جمع شدند.

آن را امتحان کنید!

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