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

תשובה

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

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

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