דף זה תורגם על ידי Cloud Translation API.

ממשק ה-API הראשי לדיווח - מדריך הפניות

מסמך זה מספק את ההפניה המלאה לשאילתה ולתגובה לממשק ה-API לגרסה 3.0.

מבוא

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

שליחת בקשה

ה-API מספק שיטה אחת לבקשת נתונים:

analytics.data.ga.get()

השיטה הזו מוצגת במגוון ספריות לקוח, ויש בה ממשקים ספציפיים לשפה כדי להגדיר את הפרמטרים של השאילתות.

אפשר גם לשלוח שאילתות ל-API כנקודת קצה ל-REST:

Authorization: Bearer {oauth2-token}

GET https://www.googleapis.com/analytics/v3/data/ga
  ?ids=ga:12345
  &start-date=2008-10-01
  &end-date=2008-10-31
  &metrics=ga:sessions,ga:bounces

כל פרמטר של שאילתת כתובת URL מציין פרמטר של שאילתת API שחייב להיות מקודד של כתובת URL.

סיכום הפרמטרים של השאילתה

בטבלה הבאה מסוכם כל הפרמטרים של שאילתות שאושרו על ידי Core Reporting API. לוחצים על כל שם של פרמטר כדי לקבל תיאור מפורט.

שם	ערך	חובה	סיכום
`ids`	`string`	כן	מזהה הטבלה הייחודי של הטופס ga:XXXX, שבו XXXX הוא מזהה התצוגה המפורטת (הפרופיל) ב-Analytics שעבורו השאילתה תאחזר את הנתונים.
`start-date`	`string`	כן	תאריך ההתחלה של אחזור נתוני Analytics. בקשות עשויות לציין תאריך התחלה בפורמט `YYYY-MM-DD`, או כתאריך יחסי (למשל, `today`, `yesterday` או `NdaysAgo` כאשר `N` הוא מספר שלם חיובי).
`end-date`	`string`	כן	תאריך הסיום לאחזור הנתונים של Analytics. ניתן לציין תאריך סיום בפורמט `YYYY-MM-DD`, או כתאריך יחסי (למשל, `today`, `yesterday` או `NdaysAgo` כאשר `N` הוא מספר שלם חיובי).
`metrics`	`string`	כן	רשימה של מדדים המופרדים בפסיקים, כמו `ga:sessions,ga:bounces`.
`dimensions`	`string`	no	רשימה של מאפיינים המופרדים בפסיקים עבור הנתונים שלכם ב-Analytics, כגון `ga:browser,ga:city`.
`sort`	`string`	no	רשימה של מאפיינים ומדדים המופרדים בפסיקים, שמציינים את סדר המיון ואת כיוון המיון של הנתונים שהוחזרו.
`filters`	`string`	no	מסננים של מאפיינים או מדדים שמגבילים את הנתונים שהוחזרו עבור הבקשה שלך.
`segment`	`string`	no	לפלח את הנתונים שהוחזרו עבור הבקשה שלך.
`samplingLevel`	`string`	no	רמת הדגימה הרצויה. ערכים מורשים: `DEFAULT` — מחזירה תגובה עם גודל לדוגמה שמאזן את המהירות והדיוק. `FASTER` — מחזירה תגובה מהירה עם דגימה קטנה יותר. `HIGHER_PRECISION` — החזרת תגובה מדויקת יותר באמצעות גודל דגימה גדול, אבל התוצאה עשויה להיות איטית יותר.
`include-empty-rows`	`boolean`	no	ברירת המחדל היא TRUE; אם היא מוגדרת כ-False, השורות שבהן כל ערכי המדדים יהיו אפס יושמטו מהתשובה.
`start-index`	`integer`	no	שורת הנתונים הראשונה שצריך לאחזר, החל מ-1. אפשר להשתמש בפרמטר הזה כמנגנון עימוד יחד עם הפרמטר `max-results`.
`max-results`	`integer`	no	המספר המקסימלי של שורות שצריך לכלול בתשובה.
`output`	`string`	no	סוג הפלט הרצוי של נתוני Analytics שהוחזרו בתגובה. הערכים הקבילים הם `json` ו-`dataTable`. ברירת מחדל: `json`.
`fields`	`string`	no	בורר שמציין קבוצת משנה של שדות להכללה בתגובה.
`prettyPrint`	`string`	no	מחזירה תשובה עם כניסת פסקה ומעברי שורה. ברירת מחדל של `false`.
`userIp`	`string`	no	מציינת את כתובת ה-IP של משתמש הקצה שעבורו מתבצעת קריאת ה-API. משמש להגבלת השימוש בכל כתובת IP.
`quotaUser`	`string`	no	חלופית ל-userIp במקרים שבהם כתובת ה-IP של המשתמש אינה ידועה.
`access_token`	`string`	no	אחת מהדרכים האפשריות לספק אסימון OAuth 2.0.
`callback`	`string`	no	השם של פונקציית הקריאה החוזרת של JavaScript שמטפלת בתגובה. משמשים בבקשות ל-JavaScript JSON-P.
`key`	`string`	no	משמש להרשאת OAuth 1.0a כדי לציין את האפליקציה כדי לקבל מכסה. לדוגמה: `key=AldefliuhSFADSfasdfasdfASdf`.

פרטי פרמטר השאילתה

מזהים

ids=ga:12345

חובה.

המזהה הייחודי ששימש לאחזור הנתונים מ-Analytics. המזהה הזה הוא שרשור של מרחב השמות ga: עם המזהה של פרופיל התצוגה המפורטת (הפרופיל) ב-Analytics. אפשר לאחזר את מזהה התצוגה המפורטת (הפרופיל) באמצעות השיטה analytics.management.profiles.list, שמספקת את id במשאב 'תצוגה (פרופיל)' ב-Google Analytics Management API.

תאריך התחלה

start-date=2009-04-20

חובה.

כל הבקשות לנתוני Analytics חייבות לציין טווח תאריכים. אם לא כוללים את הפרמטרים start-date ו-end-date בבקשה, השרת מחזיר שגיאה. ערכים של תאריכים יכולים להיות עבור תאריך מסוים באמצעות התבנית YYYY-MM-DD או באופן יחסי באמצעות today, yesterday או תבנית NdaysAgo. הערכים צריכים להיות תואמים ל-[0-9]{4}-[0-9]{2}-[0-9]{2}|today|yesterday|[0-9]+(daysAgo).

הstart-date התקף המוקדם ביותר הוא 2005-01-01. אין הגבלה על מגבלת תאריך ההתחלה.

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

טווח תאריכים לדוגמה מ-7 הימים האחרונים (שהתחיל אתמול) לפי תאריכים יחסיים:

  &start-date=7daysAgo
  &end-date=yesterday

תאריך סיום

end-date=2009-05-20

חובה.

הרכישה המוקדמת ביותר מבחינת end-date היא 2005-01-01. אין מגבלה עליונה לאפליקציה end-date.

טווח תאריכים לדוגמה מ-10 הימים האחרונים (החל מהיום) לפי תאריכים יחסיים:

  &start-date=9daysAgo
  &end-date=today

מימדים

dimensions=ga:browser,ga:city

אופציונלי.

הפרמטר dimensions מפרט מדדים לפי קריטריונים נפוצים; לדוגמה, לפי ga:browser או ga:city. בעוד שניתן לבקש את המספר הכולל של צפיות בדף לאתר, ייתכן שיהיה יותר מעניין לבקש לראות את מספר הצפיות בדף בחלוקה לפי דפדפן. במקרה כזה, יוצג מספר הצפיות בדפים מ-Firefox , Internet Explorer , Chrome וכן הלאה.

כשמשתמשים ב-dimensions בבקשת נתונים, חשוב לשים לב למגבלות הבאות:

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

ערכים

metrics=ga:sessions,ga:bounces

חובה.

הנתונים הסטטיסטיים המצטברים של פעילות המשתמשים באתר שלך, כמו קליקים או צפיות בדפים. אם בשאילתה אין פרמטר dimensions, המדדים המוחזרים מספקים ערכים מצטברים בטווח התאריכים המבוקש, כמו מספר הצפיות הכולל בדפים או סך כל העזיבה מהדף הראשון. עם זאת, כאשר מאפיינים מבקשים, הערכים מפולחים לפי ערך המאפיין. לדוגמה, הבקשה של ga:pageviews עם ga:country מחזירה את המספר הכולל של צפיות בדף לכל מדינה. כשמבקשים מדדים, חשוב לזכור:

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

מיון

sort=ga:country,ga:browser

אופציונלי.

רשימה של מדדים ומאפיינים שמציינים את סדר המיון ואת כיוון המיון של הנתונים שהוחזרו.

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

מיון התוצאות של שאילתה מאפשר לשאול שאלות שונות לגבי הנתונים. לדוגמה, כדי לענות על השאלה ’"מהן המדינות המובילות שלי, ובאילו דפדפנים הם משתמשים בתדירות הגבוהה ביותר?& ניתן לשלוח שאילתה עם הפרמטר הבא. המיון הראשון מתבצע על ידי ga:country ולאחר מכן לפי ga:browser, בסדר עולה:

sort=ga:country,ga:browser

כדי להשיב על השאלה הקשורה & גרש העמודה ממוינת תחילה לפי ga:browser ואז לפי ga:country, בסדר עולה:

sort=ga:browser,ga:country

כשמשתמשים בפרמטר sort, חשוב לזכור:

מיון רק לפי ערכים של מאפיינים או מדדים שבהם השתמשת בפרמטרים dimensions או metrics. אם הבקשה תמיין בשדה שלא צוין בפרמטר או במאפיינים או במדדים, תופיע הודעת שגיאה.
כברירת מחדל, המחרוזות ממוינות בסדר אלפביתי עולה באזור en-US.
המספרים ממוינים לפי סדר מספרי עולה כברירת מחדל.
התאריכים ממוינים בסדר עולה לפי תאריך כברירת מחדל.

מסננים

filters=ga:medium%3D%3Dreferral

תחביר – סינון
מסנני סינון
סינון מסננים
שילוב מסננים
- או אופרטור
- אופרטור AND

אופציונלי.

הפרמטר filters של מחרוזת השאילתה מגביל את הנתונים שהוחזרו מהבקשה שלך. כדי להשתמש בפרמטר filters, צריך לספק מאפיין או מדד שעליו רוצים לסנן, ולאחר מכן להוסיף את ביטוי המסנן. לדוגמה, השאילתה הבאה מבקשת ga:pageviews ו-ga:browser לתצוגה המפורטת (הפרופיל) 12134, שבה המאפיין ga:browser מתחיל במחרוזת Firefox:

https://www.googleapis.com/analytics/v3/data/ga
?ids=ga:12134
&dimensions=ga:browser
&metrics=ga:pageviews
&filters=ga:browser%3D~%5EFirefox
&start-date=2007-01-01
&end-date=2007-12-31

שאילתות שסוננו מגבילות את השורות שכן (או לא) נכללות בתוצאה. כל שורה בתוצאה נבדקת בהתאם למסנן: אם המסנן תואם, השורה נשמרת ואם היא לא תואמת, השורה תושמט.

קידוד כתובת URL: ספריות הלקוח של Google API מקודדות באופן אוטומטי את מסנני הסינון.
סינון מאפיינים: הסינון מתרחש לפני מאפיינים, כך שהמדדים שמוחזרים מייצגים את סך כל המאפיינים הרלוונטיים בלבד. בדוגמה שלמעלה, מספר הצפיות בדף יהיה רק הצפיות בדף שבהן Firefox.
סינון מדדים: סינון המדדים מתרחש אחרי שהמדדים נצברים.
שילובים חוקיים: אפשר לסנן לפי מאפיין או מדד שהוא לא חלק מהשאילתה שלך, בתנאי שכל המאפיינים/המדדים בבקשה וגם המסנן הם שילובים חוקיים. לדוגמה, אפשר להריץ שאילתה לגבי רשימה מתוארת של צפיות בדפים, ולסנן אותה בדפדפן מסוים. למידע נוסף, אפשר לעיין בקטע מאפיינים וערכים.

סינון תחביר

מסנן יחיד משתמש בטופס:

ga:name operator expression

בתחביר הזה:

name [שם] – שם המאפיין או המדד שלפיו רוצים לסנן. לדוגמה: ga:pageviews מסננים לפי המדד 'צפיות בדף'.
אופרטור – מגדיר את סוג ההתאמה לסינון. האופרטורים ספציפיים למאפיינים או למדדים.
expression - מציין את הערכים שיש לכלול או לא לכלול בתוצאות. בביטויים נעשה שימוש בתחביר של ביטוי רגולרי.

אופרטורים לסינון

קיימים שישה אופרטורים של מסננים למאפיינים, ושש אופרטורים של מסננים לערכים. האופרטורים חייבים להיות בקידוד כתובות URL כדי להיכלל במחרוזות של שאילתות של כתובות URL.

טיפ: ניתן להשתמש בסייר השאילתות של פיד נתונים כדי לעצב מסננים שמחייבים קידוד של כתובת URL. הכלי ליצירת שאילתות מקודד באופן אוטומטי כתובות URL שמכילות מחרוזות ורווחים.

**מסנני מדדים**
אופרטור	תיאור	טופס בקידוד כתובות URL	דוגמאות
`==`	שווה ל-	`%3D%3D`	יש להחזיר תוצאות שבהן הזמן בדף הוא בדיוק 10 שניות: `filters=ga:timeOnPage%3D%3D10`
`!=`	לא שווה	`!%3D`	יש להחזיר תוצאות שבהן משך הזמן בדף לא הוא 10 שניות: `filters=ga:timeOnPage!%3D10`
`>`	גדול מ-	`%3E`	יש להחזיר תוצאות שבהן משך הזמן בדף ארוך מ-10 שניות לפחות: `filters=ga:timeOnPage%3E10`
`<`	פחות מ-	`%3C`	יש להחזיר תוצאות שבהן משך הביקור בדף קצר מ-10 שניות בלבד: `filters=ga:timeOnPage%3C10`
`>=`	גדול מ- או שווה ל-	`%3E%3D`	יש להחזיר תוצאות שבהן משך הזמן בדף הוא 10 שניות או יותר: `filters=ga:timeOnPage%3E%3D10`
`<=`	פחות מ- או שווה ל-	`%3C%3D`	יש להחזיר תוצאות כאשר משך הביקור בדף הוא 10 שניות או פחות: `filters=ga:timeOnPage%3C%3D10`

**מסנני מאפיינים**
אופרטור	תיאור	טופס בקידוד כתובות URL	דוגמה
`==`	התאמה מדויקת	`%3D%3D`	מדדים מצטברים שבהם העיר היא אירווין: `filters=ga:city%3D%3DIrvine`
`!=`	לא תואם	`!%3D`	מדדים מצטברים שבהם העיר לא אירווין: `filters=ga:city!%3DIrvine`
`=@`	מכיל מחרוזת משנה	`%3D@`	מדדים מצטברים שבהם העיר מכילה יורק: `filters=ga:city%3D@York`
`!@`	לא מכיל מחרוזת משנה	`!@`	מדדים מצטברים שבהם העיר לא מכילה יורק: `filters=ga:city!@York`
`=~`	מכיל התאמה לביטוי הרגולרי	`%3D~`	מדדים מצטברים שבהם העיר מתחילה ב-חדש: `filters=ga:city%3D~%5ENew.*` (%5E הוא כתובת ה-URL המקודדת מתוך התו ^, שמעוגנת לתבנית בתחילת המחרוזת).
`!~`	אינו תואם ביטוי רגיל	`!~`	מדדים מצטברים שבהם העיר לא מתחילה בחדש: `filters=ga:city!~%5ENew.*`

סינון ביטויים

יש כמה כללים חשובים לגבי ביטויים מסוג סינון:

תווים שמורים של כתובות URL – תווים כמו & חייבים להיות בקידוד כתובות URL בצורה הרגילה.
תווים שמורים – יש להוסיף תווי לוכסן הפוך ופסיק בתו בריחה כשהם מופיעים בביטוי:
- נקודה ופסיק \;
- פסיק \,
ביטויים רגולריים – אפשר גם להשתמש בביטויים רגולריים בביטויי מסננים, באמצעות האופרטורים =~ ו-!~. התחביר שלהם דומה לביטויים רגולריים של Perl והם כוללים את הכללים הנוספים הבאים:
- אורך מקסימלי של 128 תווים — ביטויים רגולריים שאורכם עולה על 128 תווים, מובילים חזרה אל קוד הסטטוס של 400 Bad Request.
- תלויי אותיות רישיות – התאמת ביטויים רגולריים אינה תלוית אותיות רישיות.

שילוב מסננים

ניתן לשלב מסננים באמצעות לוגיקה בוליאנית של OR ו-AND. כך אפשר להאריך ביעילות את מגבלת הביטוי של 128 תווים.

או

האופרטור OR מוגדר באמצעות פסיק (,). הוא מקבל עדיפות על פני האופרטור של AND. לא ניתן להשתמש בו כדי לשלב מאפיינים ומדדים באותו ביטוי.

דוגמאות: (כל קוד חייב להיות מקודד)

המדינה היא (ארה"ב או קנדה):
ga:country==United%20States,ga:country==Canada

משתמשי Firefox במערכות הפעלה (Windows או Macintosh):
ga:browser==Firefox;ga:operatingSystem==Windows,ga:operatingSystem==Macintosh

וגם

האופרטור AND מוגדר באמצעות נקודה ופסיק (;). לפניו מופיע האופרטור OR, ואפשר להשתמש בו כדי לשלב מאפיינים ומדדים באותו ביטוי.

דוגמאות: (כל קוד חייב להיות מקודד)

המדינה היא ארצות הברית והדפדפן הוא Firefox:
ga:country==United%20States;ga:browser==Firefox

המדינה היא ארה"ב, והשפה לא מתחילה ב-'en':
ga:country==United%20States;ga:language!~^en.*

מערכת ההפעלה היא (Windows OR Macintosh) וגם הדפדפן הוא (Firefox OR Chrome):
ga:operatingSystem==Windows,ga:operatingSystem==Macintosh;ga:browser==Firefox,ga:browser==Chrome

המדינה היא ארצות הברית, והסשנים גדולים מ-5:
ga:country==United%20States;ga:sessions>5

פלח

segment=gaid::-10

    segment=sessions::condition::ga:medium%3D%3Dreferral

    segment=users::condition::ga:browser%3D%3DChrome

אופציונלי.

לפרטים מלאים על אופן הבקשה ליצירת פלח ב-Core Reporting API, אפשר לעיין במדריך למפתחים של פלחים.

סקירה כללית קונספטלית של פלחים, אפשר לעיין בחומר העזר בנושא פלחים וב פלחים במרכז העזרה.

מאפיינים ומדדים מותרים בפלחים.
לא ניתן להשתמש בכל המאפיינים והמדדים בפלחים. כדי לבדוק אילו מאפיינים ומדדים מותרים בפלחים, נכנסים לסייר המאפיינים והמדדים.

הערה: הקידומת dynamic:: הוצאה משימוש ב-27 במרץ 2014. מומלץ לעבור לתחביר החדש בהקדם האפשרי.

רמת דגימה

samplingLevel=DEFAULT

אופציונלי.

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

DEFAULT — מחזירה תגובה עם גודל לדוגמה שמאזן את המהירות והדיוק.
FASTER — מחזירה תגובה מהירה עם דגימה קטנה יותר.
HIGHER_PRECISION — החזרת תגובה מדויקת יותר באמצעות גודל דגימה גדול, אבל התוצאה עשויה להיות איטית יותר.

אם לא תספק/י את הדגימה, ייעשה שימוש ברמת הדגימה של DEFAULT.

בקטע דגימה מוסבר איך לחשב את אחוז הביקורים שבהם השאילתה נשלחה.

כלול-שורות ריקות

include-empty-rows=true

אופציונלי.

ברירת המחדל היא TRUE; אם היא מוגדרת כ-False, השורות שבהן כל ערכי המדדים יהיו אפס יושמטו מהתשובה. לדוגמה, אם תכללו יותר ממדד אחד בשאילתה, השורות יוסרו רק אם כל ערכי המדדים יהיו אפס. פעולה זו יכולה להיות שימושית בעת שליחת בקשה, כאשר צפוי שמספר השורות החוקיות יהיה קטן הרבה יותר ממספר ערכי המאפיינים הצפויים.

אינדקס התחלתי

start-index=10

אופציונלי.

אם לא תספקו, האינדקס ההתחלתי הוא 1. (המדדים של התוצאות מבוססים על 1. כלומר, השורה הראשונה היא השורה 1, ולא השורה 0.) אפשר להשתמש בפרמטר הזה כמנגנון עימוד, לצד הפרמטר max-results.

תוצאות מקסימליות

max-results=100

אופציונלי.

מספר השורות המקסימלי שיש לכלול בתגובה זו. אפשר להשתמש בשילוב עם start-index כדי לאחזר קבוצת משנה של רכיבים, או להשתמש בה בלבד כדי להגביל את מספר הרכיבים שיוחזרו, החל מהראשון. אם לא תספקו את max-results, השאילתה תחזיר את ברירת המחדל של 1,000 שורות.

ב-Analytics Core Reporting API אפשר להחזיר עד 10,000 שורות לכל בקשה, בלי קשר למספר הבקשות שביקשת. הוא גם יכול להחזיר פחות שורות מכפי שביקשת, אם אין הרבה פלחי מאפיינים כפי שציפית. לדוגמה, ב-ga:country יש פחות מ-300 ערכים אפשריים, ולכן כשמבצעים פילוח רק לפי מדינה, לא ניתן לקבל יותר מ-330 שורות, גם אם הגדרת את max-results לערך גבוה יותר.

פלט

output=dataTable

אופציונלי.

אפשר להשתמש בפרמטר הזה כדי להגדיר את סוג הפלט של נתוני Analytics שיוחזרו בתגובה. הערכים המותרים הם:

json — יצירת פלט של מאפיין ברירת המחדל rows בתגובה, המכיל אובייקט JSON.
dataTable — יוצרת פלט של מאפיין dataTable בתגובה, שמכיל אובייקט טבלת נתונים. ניתן להשתמש באובייקט Data Table הזה ישירות עם הרכיבים החזותיים של תרשימי Google.

אם לא תספקו תגובה, המערכת תשתמש בתגובת ברירת המחדל של JSON.

Fields

fields=rows,columnHeaders(name,dataType)

אופציונלי.

מציינת אילו שדות להחזיר בתגובה חלקית. אם משתמשים רק בקבוצת משנה של שדות בתגובת ה-API, אפשר להשתמש בפרמטר fields כדי לציין את השדות שייכללו.

הפורמט של ערך הפרמטר 'בקשה לשדות' משוחרר לחלוטין על סמך תחביר XPath. בהמשך מפורט סיכום התחביר הנתמך.

יש להשתמש ברשימה המופרדת בפסיקים כדי לבחור מספר שדות.
משתמשים ב-a/b כדי לבחור שדה ב' שנמצא בתוך שדה א'; משתמשים ב-a/b/c כדי לבחור שדה ג' שנמצא בתוך ב'.
כדי לבחור קבוצה של שדות משנה או מערכי משנה ספציפיים יש להשתמש בבורר משנה. פשוט מוסיפים ביטויים בסוגריים "( )".
לדוגמה: הפונקציה fields=columnHeaders(name,dataType) מחזירה רק את השדות name ו-dataType במערך columnHeaders. אפשר גם לציין שדה משנה יחיד, כאשר fields=columnHeader(name) הוא שווה ערך ל-fields=columnHeader/name.

prettyPrint

prettyPrint=false

אופציונלי.

הפונקציה מחזירה את התגובה בפורמט קריא למשתמשים אם true. ערך ברירת המחדל: false.

מכסת משתמשים

quotaUser=4kh4r2h4

אופציונלי.

המדיניות מאפשרת לאכוף מכסות לכל משתמש מאפליקציה בצד השרת, גם במקרים שבהם כתובת ה-IP של המשתמש לא ידועה. זה יכול לקרות, לדוגמה, באפליקציות שמריצים משימות cron ב-App Engine בשם משתמש. אפשר לבחור כל מחרוזת שרירותית שמזהה משתמש באופן ייחודי, אבל היא מוגבלת ל-40 תווים.

המדיניות הזו מבטלת את userIp אם שניהם סופקו.

תשובה

אם הבקשה תאושר, גוף התגובה יוחזר עם מבנה ה-JSON המוגדר למטה. אם הפרמטר פלט מוגדר ל-dataTable, הבקשה מחזירה גוף תגובה עם מבנה ה-JSON (טבלת הנתונים) שמוגדר למטה.

הערה: המונח "results" מתייחס לכל קבוצת השורות שתואמת לשאילתה, ואילו "response" מתייחס לקבוצת השורות שהוחזרו בדף התוצאות הנוכחי. התגובות עשויות להיות שונות אם המספר הכולל של התוצאות גדול יותר מהגודל של הדף בתגובה הנוכחית, כפי שמוסבר ב-itemsPerPage.

JSON

{
  "kind": "analytics#gaData",
  "id": string,
  "selfLink": string,
  "containsSampledData": boolean,
  "query": {
    "start-date": string,
    "end-date": string,
    "ids": string,
    "dimensions": [
      string
    ],
    "metrics": [
      string
    ],
    "include-empty-rows": boolean
    "samplingLevel": string,
    "sort": [
      string
    ],
    "filters": string,
    "segment": string,
    "start-index": integer,
    "max-results": integer
  },
  "itemsPerPage": integer,
  "totalResults": integer,
  "previousLink": string,
  "nextLink": string,
  "profileInfo": {
    "profileId": string,
    "accountId": string,
    "webPropertyId": string,
    "internalWebPropertyId": string,
    "profileName": string,
    "tableId": string
  },
  "columnHeaders": [
    {
      "name": string,
      "columnType": string,
      "dataType": string
    }
  ],
  "rows": [
    [
      string
    ]
  ],
  "sampleSize": string,
  "sampleSpace": string,
  "totalsForAllResults": [
    {
      metricName: string,
      ...
    }
  ]
}

שדות תגובה

המאפיינים של מבנה גוף התגובה מוגדרים כך:

שם הנכס	ערך	תיאור
`kind`	`string`	סוג המשאב. הערך הוא "analytics#gaData".
`id`	`string`	המזהה של תגובת הנתונים הזו.
`query`	`object`	האובייקט מכיל את כל הערכים שהועברו כפרמטרים לשאילתה. המשמעות של כל שדה מוסברת בתיאור של פרמטר השאילתה התואם.
`query.start-date`	`string`	תאריך התחלה.
`query.end-date`	`string`	תאריך סיום.
`query.ids`	`string`	מזהה טבלה ייחודי.
`query.dimensions[]`	`list`	רשימת מאפיינים של ניתוח נתונים.
`query.metrics[]`	`list`	רשימת מדדים לניתוח נתונים.
`query.samplingLevel`	`string`	`Requested sampling level.`
`query.include-empty-rows`	`boolean`	ברירת המחדל היא TRUE; אם היא מוגדרת כ-False, השורות שבהן כל ערכי המדדים יהיו אפס יושמטו מהתגובה.
`query.sort[]`	`list`	רשימת מדדים או מאפיינים שבהם הנתונים ממוינים.
`query.filters`	`string`	רשימה של מסנני מדדים או מאפיינים המופרדים בפסיקים.
`query.segment`	`string`	פלח ב-Analytics.
`query.start-index`	`integer`	התחלת האינדקס.
`query.max-results`	`integer`	מספר התוצאות המקסימלי בכל דף.
`startIndex`	`integer`	אינדקס ההתחלה של שורות שצוין על ידי פרמטר השאילתה `start-index`. ערך ברירת המחדל הוא 1.
`itemsPerPage`	`integer`	המספר המקסימלי של שורות שהתגובה יכולה להכיל, ללא קשר למספר השורות שהוחזרו בפועל. אם צוין `max-results` פרמטר השאילתה, הערך של `itemsPerPage` הוא הקטן יותר מבין `max-results` או 10,000. ערך ברירת המחדל של `itemsPerPage` הוא 1,000.
`totalResults`	`integer`	מספר השורות הכולל בתוצאת השאילתה, ללא קשר למספר השורות שהוחזרו בתגובה. בשאילתות שגורמות למספר שורות גדול, הערך `totalResults` יכול להיות גדול מ-`itemsPerPage`. מידע נוסף על `totalResults` ועל `itemsPerPage` לשאילתות גדולות זמין בקטע החלפה.
`startDate`	`string`	תאריך ההתחלה של שאילתת הנתונים, כפי שמצוין בפרמטר `start-date`.
`endDate`	`string`	תאריך הסיום של שאילתת הנתונים, כפי שמצוין בפרמטר `end-date`.
`selfLink`	`string`	קישור לדף התוצאות הזה עבור שאילתת הנתונים הזו.
`previousLink`	`string`	קישור לדף התוצאות הקודם של שאילתת הנתונים הזו.
`nextLink`	`string`	קישור לדף התוצאות הבא עבור שאילתת הנתונים הזו.
`profileInfo`	`object`	מידע על התצוגה המפורטת (הפרופיל) שעבורה נשלחה בקשה להצגת הנתונים. נתוני תצוגה (פרופיל) זמינים דרך Google Analytics Management API.
`profileInfo.profileId`	`string`	מזהה התצוגה המפורטת (הפרופיל) כמו `1174`.
`profileInfo.accountId`	`string`	מספר החשבון שאליו התצוגה המפורטת (פרופיל) הזו שייכת, למשל `30481`.
`profileInfo.webPropertyId`	`string`	מזהה נכס אינטרנט שאליו שייכת התצוגה המפורטת הזו (פרופיל), כגון `UA-30481-1`.
`profileInfo.internalWebPropertyId`	`string`	מזהה פנימי של נכס האינטרנט שאליו שייכת התצוגה המפורטת (פרופיל), כגון `UA-30481-1`.
`profileInfo.profileName`	`string`	שם התצוגה המפורטת (פרופיל).
`profileInfo.tableId`	`string`	מזהה טבלה לתצוגה (פרופיל), המורכב מ-"ga:" ואחריו מזהה התצוגה המפורטת (הפרופיל).
`containsSampledData`	`boolean`	הערך הוא True אם התגובה מכילה נתוני דגימה.
`sampleSize`	`string`	מספר הדגימות המשמשות לחישוב נתוני הדגימה.
`sampleSpace`	`string`	גודל המדגם הכולל. המדד הזה מציין את הגודל הכולל של השטח הזמין שממנו נבחרו הדוגמאות.
`columnHeaders[]`	`list`	כותרות של עמודות עם שמות מאפיינים, ואחרייהם שמות המדדים. סדר המאפיינים והמדדים זהה לאלה שצוינו בבקשה באמצעות הפרמטרים `metrics` ו-`dimensions`. מספר הכותרות הוא מספר המאפיינים + מספר המדדים.
`columnHeaders[].name`	`string`	שם המאפיין או המדד.
`columnHeaders[].columnType`	`string`	סוג עמודה. &"DIMENSION" או "METRIC".
`columnHeaders[].dataType`	`string`	סוג הנתונים. בכותרות של עמודת מאפיין יש `STRING` רק כסוג נתונים. כותרות של עמודות מדדים כוללות סוגי נתונים עבור ערכי מדדים כמו `INTEGER`, `PERCENT`, `TIME`, `CURRENCY`, `FLOAT` וכו'. יש לעיין בתגובה ל-API של המטא-נתונים עבור כל סוגי הנתונים האפשריים.
`totalsForAllResults`	`object`	הערכים הכוללים של המדדים המבוקשים כצמדים של ערכי מפתח של שמות וערכים. סדר הערכים הכולל זהה לזה של מדד המדד שצוין בבקשה.
`rows[]`	`list`	שורות של נתוני Analytics, כאשר כל שורה מכילה רשימה של ערכי מאפיינים ולאחר מכן ערכי המדדים. סדר המאפיינים והמדדים זהה לזה שצוין בבקשה. כל שורה כוללת רשימה של שדות N, כאשר N = מספר המאפיינים + מספר הערכים.

JSON (טבלת נתונים)

{
  "kind": "analytics#gaData",
  "id": string,
  "selfLink": string,
  "containsSampledData": boolean,
  "query": {
    "start-date": string,
    "end-date": string,
    "ids": string,
    "dimensions": [
      string
    ],
    "metrics": [
      string
    ],
    "samplingLevel": string,
    "include-empty-rows": boolean,
    "sort": [
      string
    ],
    "filters": string,
    "segment": string,
    "start-index": integer,
    "max-results": integer
  },
  "itemsPerPage": integer,
  "totalResults": integer,
  "previousLink": string,
  "nextLink": string,
  "profileInfo": {
    "profileId": string,
    "accountId": string,
    "webPropertyId": string,
    "internalWebPropertyId": string,
    "profileName": string,
    "tableId": string
  },
  "columnHeaders": [
    {
      "name": string,
      "columnType": string,
      "dataType": string
    }
  ],
  "dataTable": {
    "cols": [
      {
        "id": string,
        "label": string,
        "type": string
      }
    ],
    "rows": [
      {
        "c": [
          {    
            "v": string
          }
        ]
      }   
    ]
  },
  "sampleSize": string,
  "sampleSpace": string,
  "totalsForAllResults": [
    {
      metricName: string,
      ...
    }
  ]
}

שדות תגובה

המאפיינים של מבנה גוף התגובה מוגדרים כך:

שם הנכס	ערך	תיאור
`kind`	`string`	סוג המשאב. הערך הוא "analytics#gaData".
`id`	`string`	המזהה של תגובת הנתונים הזו.
`query`	`object`	האובייקט מכיל את כל הערכים שהועברו כפרמטרים לשאילתה. המשמעות של כל שדה מוסברת בתיאור של פרמטר השאילתה התואם.
`query.start-date`	`string`	תאריך התחלה.
`query.end-date`	`string`	תאריך סיום.
`query.ids`	`string`	מזהה טבלה ייחודי.
`query.dimensions[]`	`list`	רשימת מאפיינים של ניתוח נתונים.
`query.metrics[]`	`list`	רשימת מדדים לניתוח נתונים.
`query.samplingLevel`	`string`	`Requested sampling level.`
`query.include-empty-rows`	`boolean`	ברירת המחדל היא TRUE; אם היא מוגדרת כ-False, השורות שבהן כל ערכי המדדים יהיו אפס יושמטו מהתגובה.
`query.sort[]`	`list`	רשימת מדדים או מאפיינים שבהם הנתונים ממוינים.
`query.filters`	`string`	רשימה של מסנני מדדים או מאפיינים המופרדים בפסיקים.
`query.segment`	`string`	פלח ב-Analytics.
`query.start-index`	`integer`	התחלת האינדקס.
`query.max-results`	`integer`	מספר התוצאות המקסימלי בכל דף.
`startIndex`	`integer`	אינדקס ההתחלה של שורות שצוין על ידי פרמטר השאילתה `start-index`. ערך ברירת המחדל הוא 1.
`itemsPerPage`	`integer`	המספר המקסימלי של שורות שהתגובה יכולה להכיל, ללא קשר למספר השורות שהוחזרו בפועל. אם צוין `max-results` פרמטר השאילתה, הערך של `itemsPerPage` הוא הקטן יותר מבין `max-results` או 10,000. ערך ברירת המחדל של `itemsPerPage` הוא 1,000.
`totalResults`	`integer`	מספר השורות הכולל בתוצאת השאילתה, ללא קשר למספר השורות שהוחזרו בתגובה. בשאילתות שגורמות למספר שורות גדול, הערך `totalResults` יכול להיות גדול מ-`itemsPerPage`. מידע נוסף על `totalResults` ועל `itemsPerPage` לשאילתות גדולות זמין בקטע החלפה.
`startDate`	`string`	תאריך ההתחלה של שאילתת הנתונים, כפי שמצוין בפרמטר `start-date`.
`endDate`	`string`	תאריך הסיום של שאילתת הנתונים, כפי שמצוין בפרמטר `end-date`.
`selfLink`	`string`	קישור לדף התוצאות הזה עבור שאילתת הנתונים הזו.
`previousLink`	`string`	קישור לדף התוצאות הקודם של שאילתת הנתונים הזו.
`nextLink`	`string`	קישור לדף התוצאות הבא עבור שאילתת הנתונים הזו.
`profileInfo`	`object`	מידע על התצוגה המפורטת (הפרופיל) שעבורה נשלחה בקשה להצגת הנתונים. נתוני תצוגה (פרופיל) זמינים דרך Google Analytics Management API.
`profileInfo.profileId`	`string`	מזהה התצוגה המפורטת (הפרופיל) כמו `1174`.
`profileInfo.accountId`	`string`	מספר החשבון שאליו התצוגה המפורטת (פרופיל) הזו שייכת, למשל `30481`.
`profileInfo.webPropertyId`	`string`	מזהה נכס אינטרנט שאליו שייכת התצוגה המפורטת הזו (פרופיל), כגון `UA-30481-1`.
`profileInfo.internalWebPropertyId`	`string`	מזהה פנימי של נכס האינטרנט שאליו שייכת התצוגה המפורטת (פרופיל), כגון `UA-30481-1`.
`profileInfo.profileName`	`string`	שם התצוגה המפורטת (פרופיל).
`profileInfo.tableId`	`string`	מזהה טבלה לתצוגה (פרופיל), המורכב מ-"ga:" ואחריו מזהה התצוגה המפורטת (הפרופיל).
`containsSampledData`	`boolean`	הערך הוא True אם התגובה מכילה נתוני דגימה.
`sampleSize`	`string`	מספר הדגימות המשמשות לחישוב נתוני הדגימה.
`sampleSpace`	`string`	גודל המדגם הכולל. המדד הזה מציין את הגודל הכולל של השטח הזמין שממנו נבחרו הדוגמאות.
`columnHeaders[]`	`list`	כותרות של עמודות עם שמות מאפיינים, ואחרייהם שמות המדדים. סדר המאפיינים והמדדים זהה לאלה שצוינו בבקשה באמצעות הפרמטרים `metrics` ו-`dimensions`. מספר הכותרות הוא מספר המאפיינים + מספר המדדים.
`columnHeaders[].name`	`string`	שם המאפיין או המדד.
`columnHeaders[].columnType`	`string`	סוג עמודה. &"DIMENSION" או "METRIC".
`columnHeaders[].dataType`	`string`	סוג הנתונים. בכותרות של עמודת מאפיין יש `STRING` רק כסוג נתונים. כותרות של עמודות מדדים כוללות סוגי נתונים עבור ערכי מדדים כמו `INTEGER`, `PERCENT`, `TIME`, `CURRENCY`, `FLOAT` וכו'. יש לעיין בתגובה ל-API של המטא-נתונים עבור כל סוגי הנתונים האפשריים.
`totalsForAllResults`	`object`	הערכים הכוללים של המדדים המבוקשים כצמדים של ערכי מפתח של שמות וערכים. סדר הערכים הכולל זהה לזה של מדד המדד שצוין בבקשה.
`dataTable`	`object`	אובייקט טבלת נתונים שניתן להשתמש בו עם תרשימי Google.
`dataTable.cols[]`	`list`	רשימת מתארים של עמודות עבור מאפיינים ולאחר מכן מדדים. סדר המאפיינים והמדדים זהה לזה שצוין בבקשה באמצעות הפרמטרים `metrics` ו-`dimensions`. מספר העמודות הוא מספר המאפיינים + מספר המדדים.
`dataTable.cols[].id`	`string`	מזהה, שאפשר להשתמש בו כדי להתייחס לעמודה ספציפית (חלופה לשימוש באינדקסים של עמודות). המזהה של המאפיין או המדד משמש להגדרת הערך הזה.
`dataTable.cols[].label`	`string`	תווית לעמודה (שיכולה להופיע בתצוגה חזותית). המזהה של המאפיין או המדד משמש להגדרת הערך הזה.
`dataTable.cols[].type`	`string`	סוג הנתונים בעמודה הזו.
`dataTable.rows[]`	`list`	שורות של נתונים ב-Analytics בפורמט טבלת נתונים, כאשר כל שורה היא אובייקט עם רשימה של ערכי תאים למאפיינים שכוללים מדדים. סדר המאפיינים והמדדים זהה לזה שצוין בבקשה. בכל תא יש רשימה של שדות N, כאשר N = מספר המאפיינים + מספר המדדים.

קודי שגיאה

ממשק ה-API הראשי לדיווח מחזיר קוד מצב 200 של HTTP אם בקשה מוצלחת. אם מתרחשת שגיאה במהלך העיבוד של שאילתה, ה-API מחזיר קוד שגיאה ותיאור. כל אפליקציה שמשתמשת ב-API של Analytics צריכה להטמיע לוגיקת טיפול נכונה בשגיאות. לקבלת פרטים על קודי השגיאה ועל הטיפול בהם, יש לקרוא את מדריך העזר לתשובות לשגיאות.

רוצה לנסות?

אתם יכולים לנסות לשלוח שאילתות ל-Core Reporting API.

כדי לראות את השילובים החוקיים של המדדים והמאפיינים בשאילתה, צריך להזין ערכים לדוגמה לפרמטרים ב-Query Explorer. התוצאות של שאילתת הדוגמה מוצגות כטבלה עם ערכים עבור כל המדדים והמאפיינים שצוינו.
כדי להגיש בקשה לגבי נתונים בזמן אמת ולראות את התגובה בפורמט JSON, אפשר לנסות את השיטה analytics.data.ga.get ב-Google Data APIs Explorer.

דגימה

מערכת Google Analytics מחשבת שילובים מסוימים של מאפיינים ומדדים בזמן אמת. כדי להחזיר את הנתונים בזמן סביר, מערכת Google Analytics עשויה לעבד רק דגימה של הנתונים.

כדי לציין את רמת הדגימה שבה יש להשתמש בבקשה, אפשר להגדיר את הפרמטר דגימה.

אם תגובת Core API API מכילה דגימות נתונים, שדה התגובה containsSampledData יהיה true. בנוסף, שני נכסים יספקו מידע על רמת הדגימה עבור השאילתה: sampleSize וsampleSpace. בעזרת שני הערכים האלה, אפשר לחשב את אחוז הסשנים שבהם נעשה שימוש בשאילתה. לדוגמה, אם sampleSize הוא 201,000 ו-sampleSpace הוא 220,000, הדוח מבוסס על (201,000 / 220,000) * 100 = 91.36% מהביקורים.

בקטע דגימה יש תיאור כללי של הדגימה והשימוש בה ב-Google Analytics.

טיפול בתוצאות נתונים גדולות

אם השאילתה שלך עשויה להחזיר קבוצת תוצאות גדולה, מומלץ לפעול לפי ההנחיות שבהמשך כדי לבצע אופטימיזציה לשאילתת ה-API, להימנע משגיאות ולצמצם את החריגות של המכסה. לידיעתכם, אנחנו מגדירים בסיס ביצועים מקסימלי בכך שהוא מאפשר עד 7 מאפיינים ו-10 מדדים בכל בקשת API. שאילתות מסוימות שמציינות מספר גדול של מדדים ומאפיינים עשויות להימשך זמן רב יותר מאשר שאילתות אחרות, אבל ייתכן שההגבלה של מספר המדדים הנדרשים לא תספיק כדי לשפר את ביצועי השאילתה. במקום זאת, אפשר להשתמש בשיטות הבאות כדי לקבל את תוצאות הביצועים הטובות ביותר.

הקטנת המאפיינים לכל שאילתה

ה-API מאפשר לציין עד 7 מאפיינים בכל בקשה. פעמים רבות, מערכת Google Analytics צריכה לחשב את התוצאות של השאילתות המורכבות האלה בזמן אמת. פעולה זו עשויה לגזול זמן רב במיוחד אם מספר השורות שהתקבלו גבוה. לדוגמה, שאילתות לפי מילות מפתח, לפי עיר לפי שעה, עשויות להתאים למיליוני שורות של נתונים. כדי לשפר את הביצועים, אפשר לצמצם את מספר השורות שנדרש ל-Google Analytics על ידי הגבלת מספר המאפיינים בשאילתה.

פיצול השאילתה לפי טווח תאריכים

במקום לעבור בין התוצאות עם מפתח התאריך של טווח תאריכים ארוך, כדאי ליצור שאילתות נפרדות לשבוע אחד – או אפילו ליום אחד – בכל פעם. כמובן, עבור מערך נתונים גדול, אפילו בקשה של יום אחד עשויה להחזיר יותר מ-max-results. במקרה כזה, אין אפשרות לעבור בין דפים. אבל בכל מקרה, אם מספר השורות התואמות לשאילתה יהיה גבוה מ-max-results, פיצול טווח התאריכים עלול לקצר את משך הזמן הכולל לאחזור התוצאות. הגישה הזו יכולה לשפר את הביצועים גם בשאילתות של שרשור אחד וגם בשאילתות מקבילות.

חלוקה לדפים

מעבר בין התוצאות יכול להיות דרך נוחה לפרוץ קבוצות גדולות של תוצאות בקבוצות שניתנות לניהול. השדה totalResults מציין את מספר השורות התואמות, ו-itemsPerPage מציין את המספר המקסימלי של שורות שניתן להחזיר בתוצאה. אם יש יחס גבוה של totalResults ביחס ל-itemsPerPage, ייתכן שהשאילתות הנפרדות יימשכו זמן רב יותר מהנדרש. אם צריך רק מספר מוגבל של שורות, למשל למטרות תצוגה, כדאי להגדיר מגבלה מפורשת על גודל התגובה באמצעות הפרמטר max-results. עם זאת, אם הבקשה תצטרך לעבד קבוצה גדולה של תוצאות בשלמותה, הבקשה לקבלת השורות המקסימליות המותרות עשויה להיות יעילה יותר.

שימוש ב-gzip

דרך קלה ונוחה לצמצום רוחב הפס הדרוש לכל בקשה היא להפעיל דחיסת Gzip. לשם כך צריך להשקיע זמן נוסף של מעבד (CPU) כדי לבטל את הדחיסה של התוצאות, אבל בדרך כלל הכדאיות של עלויות הרשת משתלמת במיוחד. כדי לקבל תגובה בקידוד gzip, עליך לבצע שתי פעולות: להגדיר כותרת Accept-Encoding, ולשנות את סוכן המשתמש כך שיכיל את המחרוזת gzip. הנה דוגמה לכותרות HTTP שנוצרו כראוי להפעלת דחיסת gzip:

Accept-Encoding: gzip
User-Agent: my program (gzip)