נדרשת הרשאה
הרצת שאילתות על נתוני תנועת החיפוש באמצעות מסננים ופרמטרים שאתם מגדירים. השיטה מחזירה אפס שורות או יותר שמקובצות לפי מפתחות השורות (מאפיינים) שהגדרתם. עליך להגדיר טווח תאריכים של יום אחד או יותר.
כאשר תאריך הוא אחד מהמאפיינים, כל הימים ללא נתונים מושמטים מרשימת התוצאות. כדי לברר באילו ימים יש נתונים, מנפיקים שאילתה ללא מסננים המקובצים לפי תאריך, עבור טווח התאריכים הרצוי.
התוצאות ממוינות לפי מספר הקליקים בסדר יורד. אם לשתי שורות יש אותו מספר קליקים, הן ממוינות באופן שרירותי.
ראה את דוגמת python לקריאה לשיטה זו.
ה-API מוגבל על ידי מגבלות פנימיות של Search Console, ואינו מבטיח להחזיר את כל שורות הנתונים אלא את השורות המובילות.
כאן אפשר לראות את המגבלות על כמות הנתונים הזמינה.
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 |
[אופציונלי] מסננים את התוצאות לפי הסוג הבא:
|
|
dimensionFilterGroups[] |
list |
[אופציונלי] אפס קבוצות או יותר של מסננים שניתן להחיל על הערכים של קיבוץ המאפיינים. כל קבוצות הסינון צריכות להתאים כדי שתוחזר שורה בתגובה. בקבוצת מסננים אחת אפשר לציין אם כל המסננים חייבים להתאים, או שלפחות אחד מהם חייב להתאים. | |
dimensionFilterGroups[].groupType |
string |
אם כל המסננים בקבוצה הזו חייבים להחזיר true ("and"), או אם אחד או יותר חייבים להחזיר true (עדיין לא נתמך).
הערכים הקבילים הם:
|
|
dimensionFilterGroups[].filters[] |
list |
[אופציונלי] אפס מסננים או יותר לבדיקה מול השורה. כל מסנן כולל שם מאפיין, אופרטור וערך. אורך מקסימלי של 4,096 תווים. דוגמאות:
country equals FRA query contains mobile use device notContains tablet |
|
dimensionFilterGroups[].filters[].dimension |
string |
המאפיין שעליו חל המסנן הזה. אפשר לסנן לפי כל מאפיין שמופיע כאן, גם אם לא מקובצים לפי המאפיין הזה.
הערכים הקבילים הם:
|
|
dimensionFilterGroups[].filters[].operator |
string |
[אופציונלי] איך הערך שצוין חייב להתאים (או לא להתאים) לערך המאפיין של השורה.
הערכים הקבילים הם:
|
|
dimensionFilterGroups[].filters[].expression |
string |
הערך של המסנן שצריך להתאים או להחריג, בהתאם לאופרטור. | |
aggregationType |
string |
[אופציונלי] איך הנתונים נצברים. אם הנתונים נצברים לפי נכס, כל הנתונים של אותו נכס נצברים. אם הנתונים נצברים לפי דף, כל הנתונים נצברים לפי URI קנוני. אם מסננים או מקבצים לפי דף, צריך לבחור אוטומטי. אחרת, אפשר לצבור לפי נכס או לפי דף, בהתאם לאופן שבו רוצים לחשב את הנתונים. במסמכי העזרה מוסבר איך הנתונים מחושבים לפי אתר לעומת אופן החישוב של הנתונים לפי דף. הערה: אם מקבצים או מסננים לפי דף, לא ניתן לצבור לפי נכס. אם מציינים ערך כלשהו שאינו 'אוטומטי', סוג הצבירה בתוצאה יתאים לסוג המבוקש. אם תבקשו סוג לא חוקי, תתקבל הודעת שגיאה. אם הסוג המבוקש לא תקין, ה-API לעולם לא ישנה את סוג הצבירה. הערכים הקבילים הם:
|
|
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 |
איך הצטברו התוצאות.אפשר לעיין במסמכי העזרה כדי ללמוד איך הנתונים מחושבים באופן שונה לפי אתר לעומת לפי דף.
הערכים הקבילים הם:
|
רוצה לנסות?
ניתן להשתמש ב-APIs Explorer שבהמשך כדי לקרוא לשיטה הזו בנתונים בזמן אמת ולראות את התגובה.