נדרשת הרשאה
הרצת שאילתות על נתוני תנועת החיפוש באמצעות מסננים ופרמטרים שאתם מגדירים. השיטה מחזירה אפס שורות או יותר שמקובצות לפי מפתחות השורות (מאפיינים) שהגדרתם. עליך להגדיר טווח תאריכים של יום אחד או יותר.
כשתאריך הוא אחד מהמאפיינים, ימים ללא נתונים מושמטים מרשימת התוצאות. כדי לדעת באילו ימים יש נתונים, אפשר ליצור שאילתה ללא מסננים שמקובצים לפי תאריך, בטווח התאריכים הרצוי.
התוצאות ממוינות לפי מספר הקליקים בסדר יורד. אם בשתי שורות יש אותו מספר קליקים, הן ממוינות באופן שרירותי.
כדי להפעיל את השיטה הזו, אפשר לעיין בדוגמת 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
פרמטרים
שם הפרמטר | ערך של Gpa education | תיאור |
---|---|---|
פרמטרים של נתיב | ||
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 }
שם הנכס | ערך של Gpa education | תיאור | הערות |
---|---|---|---|
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'.המערכת משלבת את ערכי מאפייני הקיבוץ כדי ליצור מפתח ייחודי לכל שורה בתוצאות. אם לא תציינו מאפיינים, כל הערכים ישולבו לשורה אחת. אין הגבלה על מספר המאפיינים שאפשר לקבץ לפיהם, אבל אי אפשר לקבץ לפי אותו מאפיין פעמיים. לדוגמה: [מדינה, מכשיר] | |
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 |
[אופציונלי] אם הערך הוא 'הכול' (לא תלוי-רישיות), הנתונים יכללו נתונים חדשים. אם הפרמטר 'Final' (לא תלוי-רישיות) או אם הוא מושמט, הנתונים המוחזרים יכללו רק את הנתונים הסופיים. |
תשובה
התוצאות מקובצות לפי המאפיינים שצוינו בבקשה. כל הערכים עם אותה קבוצה של ערכי מאפיינים יקובצו לשורה אחת. לדוגמה, אם מקבצים לפי מאפיין המדינה, כל התוצאות עבור ארה"ב יקובצו יחד, כל התוצאות של mdv יקובצו יחד וכן הלאה. אם קיבוץ לפי מדינה ומכשיר, כל התוצאות עבור 'ארה"ב, טאבלט' יקובצו, כל התוצאות עבור 'ארה"ב, נייד' יקובצו יחד וכן הלאה. במסמכי התיעוד של דוח ניתוח החיפוש ניתן לקבל מידע ספציפי על אופן החישוב של קליקים, חשיפות וכו' והמשמעות שלהם.
התוצאות ממוינות לפי מספר הקליקים, בסדר יורד, אלא אם מקבצים לפי תאריך. במקרה כזה התוצאות ממוינות לפי תאריך, בסדר עולה (מהישן לחדש, האחרון). אם יש שוויון בין שתי שורות, סדר המיון הוא שרירותי.
כדאי לעיין במאפיין rowLimit בבקשה כדי לראות את מספר הערכים המקסימלי שאפשר להחזיר.
{ "rows": [ { "keys": [ string ], "clicks": double, "impressions": double, "ctr": double, "position": double } ], "responseAggregationType": string }
שם הנכס | ערך של Gpa education | תיאור | הערות |
---|---|---|---|
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 שבהמשך כדי להפעיל את השיטה הזו בנתונים בזמן אמת ולראות את התגובה.