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

פרמטרים

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