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

פרמטרים

שם הפרמטר Value התיאור
פרמטרים של נתיב
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
}
שם הנכס Value התיאור הערות
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': תוצאות ב-Discover
  • "googleNews": תוצאות מהאתר news.google.com ומאפליקציית חדשות Google ל-Android ול-iOS. לא כולל תוצאות מהכרטיסייה 'חדשות' בחיפוש Google.
  • 'news': תוצאות חיפוש מהכרטיסייה 'חדשות' בחיפוש Google.
  • 'image': תוצאות חיפוש מהכרטיסייה 'תמונה' בחיפוש Google.
  • "video": תוצאות חיפוש של סרטונים
  • "web": [ברירת מחדל] סינון התוצאות לכרטיסייה המשולבת ("הכול") בחיפוש Google. לא כולל תוצאות של Discover או של חדשות Google.
dimensionFilterGroups[] list [אופציונלי] אפס קבוצות או יותר של מסננים שניתן להחיל על הערכים של קיבוץ המאפיינים. כל קבוצות הסינון צריכות להתאים כדי שתוחזר שורה בתגובה. בקבוצת מסננים אחת אפשר לציין אם כל המסננים חייבים להתאים, או שלפחות אחד מהם חייב להתאים.
dimensionFilterGroups[].groupType string אם כל המסננים בקבוצה הזו חייבים להחזיר true ("and"), או אם אחד או יותר חייבים להחזיר 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': סינון לפי תכונה ספציפית של תוצאות חיפוש. כדי להציג רשימה של הערכים הזמינים, מריצים שאילתה המקובצת לפי "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 [אופציונלי] אם 'הכול' (לא תלוי-רישיות), הנתונים יכללו נתונים עדכניים. אם הפרמטר 'סופי' (לא תלוי-רישיות) או אם הפרמטר מושמט, הנתונים שיוחזרו יכללו רק נתונים סופיים.

תשובה

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

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

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

{
  "rows": [
    {
      "keys": [
        string
      ],
      "clicks": double,
      "impressions": double,
      "ctr": double,
      "position": double
    }
  ],
  "responseAggregationType": string
}
שם הנכס Value התיאור הערות
rows[] list רשימה של שורות המקובצות לפי ערכי המפתח לפי הסדר הנתון בשאילתה.
rows[].keys[] list רשימה של ערכי המאפיינים עבור אותה שורה, המקובצים לפי המאפיינים בבקשה, בסדר שצוין בבקשה.
rows[].clicks double לחץ על count עבור השורה.
rows[].impressions double מספר החשיפות בשורה.
rows[].ctr double שיעור קליקים (CTR) בשורה. הערכים נעים בין 0 ל-1.0, כולל.
rows[].position double מיקום ממוצע בתוצאות החיפוש.
responseAggregationType string איך הצטברו התוצאות.אפשר לעיין במסמכי העזרה כדי ללמוד איך הנתונים מחושבים באופן שונה לפי אתר לעומת לפי דף.

הערכים הקבילים הם:
  • "auto"
  • "byPage": התוצאות נצברו לפי דף.
  • 'byProperty': התוצאות נצברו לפי נכס.

רוצה לנסות?

ניתן להשתמש ב-APIs Explorer שבהמשך כדי לקרוא לשיטה הזו בנתונים בזמן אמת ולראות את התגובה.