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 ‫[Required] תאריך ההתחלה של טווח התאריכים המבוקש, בפורמט YYYY-MM-DD, בשעון החוף הפסיפי (UTC - 7:00/8:00). חייב להיות קטן מתאריך הסיום או שווה לו. הערך הזה נכלל בטווח.
endDate string ‫[Required] תאריך הסיום של טווח התאריכים המבוקש, בפורמט YYYY-MM-DD, בשעון החוף הפסיפי (UTC - 7:00/8:00). התאריך חייב להיות מאוחר מתאריך ההתחלה או זהה לו. הערך הזה נכלל בטווח.
dimensions[] list ‫[Optional] אפס או יותר מאפיינים לקיבוץ התוצאות. התוצאות מקובצות לפי הסדר שבו ציינתם את המאפיינים האלה. אפשר להשתמש בכל שם של מאפיין ב-dimensionFilterGroups[].filters[].dimension, וגם ב-date (תאריך) וב-hour (שעה). ערכי המאפיין של הקיבוץ משולבים כדי ליצור מפתח ייחודי לכל שורת תוצאה. אם לא מציינים מאפיינים, כל הערכים ישולבו בשורה אחת. אין הגבלה על מספר המאפיינים שאפשר לקבץ לפיהם, אבל אי אפשר לקבץ לפי אותו מאפיין פעמיים. דוגמה: [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": סינון התוצאות לפי סוג המכשיר שצוין. ערכים נתמכים:
    • מחשב
    • MOBILE
    • TABLET
  • ‫"page": סינון לפי מחרוזת ה-URI שצוינה.
  • ‫"query": סינון לפי מחרוזת השאילתה שצוינה.
  • ‫"searchAppearance": סינון לפי תוצאת חיפוש מיוחדת ספציפית. כדי לראות רשימה של הערכים הזמינים, מריצים שאילתה שמקובצת לפי searchAppearance. רשימה מלאה של הערכים והתיאורים זמינה גם במסמכי העזרה.
dimensionFilterGroups[].filters[].operator string ‫[Optional] איך הערך שציינתם צריך להתאים (או לא להתאים) לערך המאפיין בשורה.

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

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

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

אם מציינים ערך כלשהו שאינו auto, סוג הצבירה בתוצאה יהיה זהה לסוג המבוקש, או שאם מבקשים סוג לא תקין, תתקבל שגיאה. ממשק ה-API לא ישנה את סוג הצבירה אם הסוג המבוקש לא תקין.

ערכים קבילים:
  • ‫"auto": [Default] השירות יקבע את סוג הצבירה המתאים.
  • ‫"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 offset.
startRow integer [אופציונלי; ברירת המחדל היא 0] אינדקס מבוסס-אפס של השורה הראשונה בתגובה. חייב להיות מספר לא שלילי. אם הערך של startRow גדול ממספר התוצאות של השאילתה, התגובה תהיה תגובה מוצלחת עם אפס שורות.
dataState string ‫[Optional] אם הערך הוא all (לא תלוי באותיות רישיות), הנתונים יכללו נתונים עדכניים. אם הערך הוא 'final' (לא תלוי באותיות רישיות) או אם הפרמטר הזה לא מצוין, הנתונים שמוחזרים יכללו רק נתונים סופיים. אם הערך הוא hourly_all (לא תלוי באותיות רישיות), הנתונים יכללו פירוט שעתי. המשמעות היא שהנתונים השעתיים כוללים נתונים חלקיים, וצריך להשתמש בהם כשמקבצים לפי מאפיין השעה ב-API.

תשובה

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

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

במאפיין 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": התוצאות נצברו לפי נכס.
metadata object

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

כשמבקשים נתונים מהזמן האחרון (באמצעות all או hourly_all עבור dataState), יכול להיות שחלק מהשורות שיוחזרו ייצגו נתונים לא מלאים, כלומר הנתונים עדיין בתהליך של איסוף ועיבוד. אובייקט המטא-נתונים הזה עוזר לכם לזהות בדיוק מתי התקופה מתחילה ומתי היא מסתיימת.

כל התאריכים והשעות שמופיעים באובייקט הזה הם לפי אזור הזמן America/Los_Angeles.

השדה הספציפי שמוחזר באובייקט הזה תלוי באופן שבו קיבצתם את הנתונים בבקשה:

  • ‫first_incomplete_date (string): התאריך הראשון שעבורו הנתונים עדיין נאספים ומעובדים, בפורמט YYYY-MM-DD (פורמט תאריך מקומי מורחב של ISO-8601).

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

    יכול להיות שכל הערכים אחרי first_incomplete_date ישתנו באופן משמעותי.

  • ‫first_incomplete_hour (string): השעה הראשונה שבה הנתונים עדיין נאספים ומעובדים, בפורמט YYYY-MM-DDThh:mm:ss[+|-]hh:mm (פורמט מורחב של תאריך ושעה עם היסט זמן לפי ISO-8601).

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

    יכול להיות שכל הערכים אחרי first_incomplete_hour ישתנו באופן משמעותי.

רוצה לנסות?

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