Search Analytics: query

נדרשת הרשאה

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

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

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

בדוגמה ל-Python מוסבר איך לקרוא ל-method הזה.

ה-API מוגבל על ידי מגבלות פנימיות של Search Console, ואין ערובה שהוא יחזיר את כל שורות הנתונים, אלא רק את העליונות שבהן.

מידע על המגבלות על כמות הנתונים הזמינים

דוגמה לבקשת POST בפורמט JSON: 
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, לפי שעון קליפורניה (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 כדי שקבוצת המסננים תהיה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': סינון התוצאות לפי סוג המכשיר שצוין. ערכים נתמכים:
    • DESKTOP
    • נייד
    • טאבלט
  • 'page': סינון לפי מחרוזת ה-URI שצוינה.
  • 'query': סינון לפי מחרוזת השאילתה שצוינה.
  • 'searchAppearance': סינון לפי תכונה ספציפית של תוצאת חיפוש. כדי לראות רשימה של הערכים הזמינים, מריצים שאילתה שמקובצת לפי "searchsearch". הרשימה המלאה של הערכים והתיאורים זמינה גם במאמרי העזרה.
dimensionFilterGroups[].filters[].operator string [אופציונלי] האופן שבו הערך שציינתם צריך להתאים (או לא להתאים) לערך המאפיין בשורה.

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

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

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

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

ערכים קבילים:
  • "auto": [ברירת מחדל] יש לאפשר לשירות לקבוע את סוג הצבירה המתאים.
  • 'byNewsShowcasePanel': צבירת ערכים לפי לוח News Showcase. צריך להשתמש באפשרות הזו בשילוב עם המסנן 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] אינדקס שמתחיל בספרה אפס של השורה הראשונה בתגובה. צריך להזין מספר לא שלילי. אם הערך של startRow חורג ממספר התוצאות של השאילתה, התגובה תהיה תגובה מוצלחת עם אפס שורות.
dataState string [אופציונלי] אם הערך הוא 'הכול' (לא תלוי-רישיות), הנתונים יכללו נתונים חדשים. אם הפרמטר הוא 'final' (ללא קשר לאותיות רישיות) או אם הפרמטר הזה לא מצוין, הנתונים שיוחזרו יכללו רק נתונים שהושלמו.

תשובה

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