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 ‫[חובה] תאריך הסיום של טווח התאריכים המבוקש, בפורמט YYYY-MM-DD, לפי שעון החוף הפסיפי (PT) (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 ‫[Optional; Valid range is 1–25,000; Default is 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 שבהמשך כדי להפעיל את השיטה הזו על נתונים פעילים ולראות את התגובה.