Search Analytics: query

נדרשת הרשאה

הרצת שאילתות על נתוני תנועת החיפוש באמצעות מסננים ופרמטרים שאתם מגדירים. השיטה מחזירה אפס שורות או יותר שמקובצות לפי מפתחות השורות (מאפיינים) שהגדרתם. עליך להגדיר טווח תאריכים של יום אחד או יותר.

כאשר תאריך הוא אחד מהמאפיינים, ימים ללא נתונים מושמטים מרשימת התוצאות. כדי לדעת באילו ימים יש נתונים, צור שאילתה ללא מסננים המקובצים לפי תאריך, בטווח התאריכים הרצוי.

התוצאות ממוינות לפי מספר הקליקים בסדר יורד. אם לשתי שורות יש אותו מספר קליקים, הן ימוינו באופן שרירותי.

ראה את דוגמת 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 כתובת ה-URL של הנכס כפי שהוגדרה ב-Search Console. דוגמאות: 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".המערכת משלבת את הערכים של מאפייני הקיבוץ כדי ליצור מפתח ייחודי לכל שורת תוצאות. אם לא צוינו מאפיינים, כל הערכים ישולבו בשורה אחת. אין הגבלה על מספר המאפיינים שאפשר לקבץ לפיהם, אבל אי אפשר לקבץ לפי אותו מאפיין פעמיים. לדוגמה: [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 [אופציונלי] אפס קבוצות או יותר של מסננים שיחולו על הערכים של קיבוץ המאפיינים. כל קבוצות הסינון צריכות להתאים כדי שתוחזר שורה בתגובה. בקבוצת מסננים אחת ניתן לציין אם כל המסננים חייבים להתאים, או לפחות אחד מהם חייב להתאים.
dimensionFilterGroups[].groupType string אם כל המסננים בקבוצה הזו חייבים להחזיר true ("ו"), או שאחד או יותר חייבים להחזיר true (לא נתמך עדיין).

הערכים הקבילים הם:
  • "and": כל המסננים בקבוצה חייבים להחזיר true עבור קבוצת המסננים to להיות True.
dimensionFilterGroups[].filters[] list [אופציונלי] אין או יותר מסננים לבדיקה מול השורה. כל מסנן מכיל שם מאפיין, אופרטור וערך. האורך המקסימלי הוא 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': סינון לפי תכונה ספציפית של תוצאות חיפוש. כדי להציג רשימה של ערכים זמינים, מריצים שאילתה המקובצת לפי "searchMirror".
dimensionFilterGroups[].filters[].operator string [אופציונלי] איך הערך שצוין צריך להתאים (או לא להתאים) לערך המאפיין בשורה.

הערכים הקבילים הם:
  • 'contains': ערך השורה חייב להכיל את הביטוי שלך או שווה לו (לא תלוי-רישיות).
  • "equals": [ברירת מחדל] הביטוי חייב להיות שווה בדיוק לערך השורה (תלוי אותיות רישיות למאפייני הדף והשאילתה).
  • 'notContains': ערך השורה לא יכול להכיל את הביטוי שלך כמחרוזת משנה או כהתאמה מלאה (לא תלוית אותיות רישיות).
  • "notEquals": הביטוי לא יכול להיות שווה בדיוק לערך השורה (תלוי אותיות רישיות למאפייני דף ושאילתה).
  • "includingRegex": ביטוי רגולרי של תחביר RE2 שחייב להיות תואם לו.
  • "excludingRegex": ביטוי רגולרי של תחביר RE2 שאסור לו להתאים.
dimensionFilterGroups[].filters[].expression string הערך של המסנן שיש להתאים או להחריג, בהתאם לאופרטור.
aggregationType string

[אופציונלי] איך הנתונים נצברים. אם הנתונים נצברים לפי נכס, כל הנתונים של אותו נכס נצברים. אם הם נצברים לפי דף, כל הנתונים נצברים לפי URI קנוני. אם מסננים או מקבצים לפי דף, יש לבחור באופן אוטומטי. אחרת אפשר לצבור נתונים לפי נכס או לפי דף, בהתאם לאופן שבו רוצים שהנתונים יחושבו. במסמכי העזרה מוסבר איך הנתונים מחושבים לפי אתר לעומת דף.

הערה: אם מקבצים או מסננים לפי דף, לא ניתן לצבור לפי נכס.

אם מציינים ערך כלשהו שאינו 'אוטומטי', סוג הצבירה בתוצאה יתאים לסוג המבוקש. אם תבקשו סוג לא חוקי, תתקבל הודעת שגיאה. ה-API לעולם לא ישנה את סוג הצבירה שלך אם הסוג המבוקש לא חוקי.

הערכים הקבילים הם:
  • "auto": [ברירת מחדל] מתן הרשאה לשירות להחליט מה סוג הצבירה המתאים.
  • "byNewsShowcasePanel": ערכים נצברים לפי הלוח ב-News Showcase. צריך להשתמש במאפיין הזה בשילוב עם המסנן searchAppearance NEWS_SHOWCASE ועם type=discover או type=googleNews. אם מקבצים לפי דף, מסננים לפי דף או מסננים לפי searchAppearance אחר, לא ניתן לצבור לפי byNewsShowcasePanel.
  • "byPage": ערכים נצברים לפי URI.
  • "byProperty": ערכים נצברים לפי נכס. אין תמיכה ב-type=discover או ב-type=googleNews
rowLimit integer [אופציונלי; הטווח החוקי הוא 1–25,000; ברירת המחדל היא 1,000] מספר השורות המקסימלי שיש להחזיר. כדי לעבור בין תוצאות, משתמשים בהיסט startRow.
startRow integer [אופציונלי; ברירת המחדל היא 0] אינדקס מבוסס אפס של השורה הראשונה בתגובה. חייב להיות מספר לא שלילי. אם הערך של startRow חורג ממספר התוצאות לשאילתה, התשובה תהיה תשובה מוצלחת עם אפס שורות.
dataState string [אופציונלי] אם בחרתם באפשרות 'הכול' (לא תלוי-רישיות), הנתונים יכללו נתונים עדכניים. אם הפרמטר הוא "סופי" (לא תלוי-רישיות) או אם הפרמטר הזה מושמט, הנתונים המוחזרים יכללו רק נתונים סופיים.

תשובה

התוצאות מקובצות לפי המאפיינים שצוינו בבקשה. כל הערכים שיש להם אותה קבוצה של ערכי מאפיינים יקובצו בשורה אחת. לדוגמה, אם מקבצים לפי המאפיין 'מדינה', כל התוצאות שקשורות ל-'usa' יקובצו יחד, כל התוצאות של 'mdv' יקובצו יחד וכן הלאה. אם מקבצים לפי מדינה ומכשיר, כל התוצאות עבור "ארה"ב, טאבלט" יקובצו, כל התוצאות עבור "ארה"ב, מכשירים ניידים" יקובצו וכן הלאה. במסמכי התיעוד של דוח ניתוח החיפושים מפורט מידע נוסף על אופן החישוב של קליקים, חשיפות וכו', ועל המשמעות שלהם.

התוצאות ממוינות לפי מספר הקליקים בסדר יורד, אלא אם מקבצים לפי תאריך. במקרה כזה התוצאות ממוינות לפי תאריך, בסדר עולה (מהישן לחדש, מהחדש לישן). אם יש שוויון בין שתי שורות, סדר המיון הוא שרירותי.

אפשר לעיין במאפיין 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 שבהמשך כדי לקרוא לשיטה הזו בנתונים בזמן אמת ולראות את התגובה.