Search Analytics: query

נדרשת הרשאה

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

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

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

כדי להפעיל את השיטה הזו, אפשר לעיין בדוגמת python.

ה-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, לפי שעון PT (UTC - 7:00/8:00). חייב להיות גדול מתאריך ההתחלה או שווה לו. הערך הזה נכלל בטווח.
dimensions[] list [אופציונלי] אפס מאפיינים או יותר לקיבוץ התוצאות לפיהם.התוצאות מקובצות לפי הסדר שבו סיפקתם את המאפיינים האלה.אפשר להשתמש בכל שם של מאפיין ב-dimensionFilterGroups[].filters[].dimension וגם ב-'date'.המערכת משלבת את ערכי המאפיינים של הקיבוץ כדי ליצור מפתח ייחודי לכל שורה בתוצאות. אם לא תציינו מאפיינים, כל הערכים ישולבו לשורה אחת. אין הגבלה על מספר המאפיינים שאפשר לקבץ לפיהם, אבל אי אפשר לקבץ לפי אותו מאפיין פעמיים. לדוגמה: [מדינה, מכשיר]
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 עבור קבוצת המסננים t.
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': סינון לפי תכונה ספציפית של תוצאת חיפוש. כדי לראות רשימה של הערכים הזמינים, מריצים שאילתה שמקובצת לפי '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. צריך להשתמש באפשרות הזו בשילוב עם 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 [אופציונלי] אם הערך הוא 'הכול' (לא תלוי-רישיות), הנתונים יכללו נתונים חדשים. אם הוא 'סופי' (לא תלוי-רישיות) או אם הפרמטר הזה לא ייכלל, הנתונים שיוחזרו יכללו רק את הנתונים הסופיים.

תשובה

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