נדרשת הרשאה
הרצת שאילתות על נתוני תנועת החיפוש באמצעות מסננים ופרמטרים שאתם מגדירים. השיטה מחזירה אפס שורות או יותר שמקובצות לפי מפתחות השורות (מאפיינים) שהגדרתם. עליך להגדיר טווח תאריכים של יום אחד או יותר.
כאשר תאריך הוא אחד מהמאפיינים, ימים ללא נתונים מושמטים מרשימת התוצאות. כדי לדעת באילו ימים יש נתונים, צור שאילתה ללא מסננים המקובצים לפי תאריך, בטווח התאריכים הרצוי.
התוצאות ממוינות לפי מספר הקליקים בסדר יורד. אם לשתי שורות יש אותו מספר קליקים, הן ימוינו באופן שרירותי.
ראה את דוגמת 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
פרמטרים
שם הפרמטר | ערך | תיאור |
---|---|---|
פרמטרים של נתיב | ||
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 |
[חובה] תאריך ההתחלה של טווח התאריכים המבוקש, בפורמט 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 וגם ב-"date".המערכת משלבת את הערכים של מאפייני הקיבוץ כדי ליצור מפתח ייחודי לכל שורת תוצאות. אם לא צוינו מאפיינים, כל הערכים ישולבו בשורה אחת. אין הגבלה על מספר המאפיינים שאפשר לקבץ לפיהם, אבל אי אפשר לקבץ לפי אותו מאפיין פעמיים. לדוגמה: [country, device] | |
searchType |
string |
הוצא משימוש. יש להשתמש במקום זאת ב-type
|
|
type |
string |
[אופציונלי] מסננים את התוצאות לפי הסוג הבא:
|
|
dimensionFilterGroups[] |
list |
[אופציונלי] אפס קבוצות או יותר של מסננים שיחולו על הערכים של קיבוץ המאפיינים. כל קבוצות הסינון צריכות להתאים כדי שתוחזר שורה בתגובה. בקבוצת מסננים אחת ניתן לציין אם כל המסננים חייבים להתאים, או לפחות אחד מהם חייב להתאים. | |
dimensionFilterGroups[].groupType |
string |
אם כל המסננים בקבוצה הזו חייבים להחזיר true ("ו"), או שאחד או יותר חייבים להחזיר 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' יקובצו יחד וכן הלאה. אם מקבצים לפי מדינה ומכשיר, כל התוצאות עבור "ארה"ב, טאבלט" יקובצו, כל התוצאות עבור "ארה"ב, מכשירים ניידים" יקובצו וכן הלאה. במסמכי התיעוד של דוח ניתוח החיפושים מפורט מידע נוסף על אופן החישוב של קליקים, חשיפות וכו', ועל המשמעות שלהם.
התוצאות ממוינות לפי מספר הקליקים בסדר יורד, אלא אם מקבצים לפי תאריך. במקרה כזה התוצאות ממוינות לפי תאריך, בסדר עולה (מהישן לחדש, מהחדש לישן). אם יש שוויון בין שתי שורות, סדר המיון הוא שרירותי.
אפשר לעיין במאפיין 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 |
איך התוצאות נצברו.אפשר לעיין במסמכי העזרה כדי ללמוד איך נתונים מחושבים באופן שונה לפי אתר לעומת לפי דף.
הערכים הקבילים הם:
|
רוצה לנסות?
צריך להשתמש ב-APIs Explorer שבהמשך כדי לקרוא לשיטה הזו בנתונים בזמן אמת ולראות את התגובה.