בדף הזה מתוארים יסודות השימוש ב-Chart API ליצירת תרשימים.
מדיניות השימוש בתרשים Google
אין הגבלה על מספר הקריאות ליום שניתן לבצע ל-API של תרשים Google. עם זאת, אנחנו שומרים את הזכות לחסום כל שימוש שאנחנו מחשיבים כפוגעני.
סקירה כללית
הצגת תרשימים במסמך התיעוד הזה
כל תמונות התרשימים במסמך הזה נוצרות באופן פעיל באמצעות Chart API. כדי להציג את כתובת ה-URL של תמונה כלשהי:
- אם משתמשים ב-Firefox, לוחצים לחיצה ימנית ואז בוחרים באפשרות 'הצגת תמונה' או 'מאפיינים'.
- אם משתמשים ב-Internet Explorer, לוחצים לחיצה ימנית ואז בוחרים באפשרות 'מאפיינים'.
כדי להקל על הקריאה של כתובת ה-URL, המסמך הזה מציג אותה לעיתים קרובות בכמה שורות. כשמשתמשים בממשק ה-API של תרשים Google, צריך לציין כתובת URL בשורה אחת.
Google Chart API מחזיר תמונת תרשים בתגובה לבקשת GET או POST של כתובת URL. ה-API יכול ליצור סוגים רבים של תרשימים, החל מתרשימי עוגה או מתרשימי קו ועד לקודי QR ונוסחאות. כל המידע לגבי התרשים הרצוי, כמו נתוני תרשים, גודל, צבעים ותוויות, הוא חלק מכתובת ה-URL. (המצב הזה קצת שונה בבקשות POST, אבל אין מה לדאוג עכשיו).
כדי ליצור תרשים פשוט ככל האפשר, כל מה שכתובת ה-URL צריכה לציין את סוג התרשים, את הנתונים ואת הגודל שלו. אפשר להקליד את כתובת ה-URL הזו ישירות בדפדפן, או להצביע עליה באמצעות תג <img>
בדף האינטרנט. למשל, אפשר ללחוץ על הקישור הבא כדי ליצור תרשים עוגה:
https://chart.googleapis.com/chart?chs=250x100&chd=t:60,40&cht=p3&chl=Hello|World
הקישור הקודם הוא דוגמה לכתובת URL בסיסית של תרשים API. לכל כתובות ה-URL של התרשימים יש את הפורמט הבא:
https://chart.googleapis.com/chart?cht=<chart_type>&chd=<chart_data>&chs=<chart_size>&...additional_parameters...
כל כתובות ה-URL מתחילות בקידומת https://chart.googleapis.com/chart?, ואחריה
הפרמטרים שמציינים את הנתונים והמראה של התרשים. הפרמטרים הם צמדי name=value,
שמופרדים באמצעות תו אמפרסנד (&), והפרמטרים יכולים
להיות בכל סדר, אחרי ?. לכל התרשימים נדרשים לפחות הפרמטרים הבאים: cht (סוג תרשים), chd (נתונים) ו-chs (גודל התרשים). עם זאת, יש עוד הרבה פרמטרים לאפשרויות נוספות, ואפשר לציין עוד פרמטרים רבים ככל האפשר לפי התרשים.
נבחן לעומק את כתובת האתר שלמעלה:
| כתובת URL | רכיבים |
|---|---|
|
|
צריך להעתיק ולהדביק את כתובת ה-URL הזו בדפדפן ולנסות לבצע כמה שינויים: להוסיף עוד ערכים לנתונים (לא לשכוח להוסיף פסיק לפני כל ערך חדש בנתונים). מוסיפים
תוויות חדשות (מוסיפים סימן | לפני כל ערך חדש). מגדילים את התרשים.
איך יוצרים תרשים
כך יוצרים תרשים תמונה:
- בוחרים את סוג התרשים. בגלריה אפשר למצוא רשימה של תרשימים.
סוג התרשים מצוין באמצעות הפרמטר
cht. משרטטים את כל הרכיבים שרוצים לכלול בתרשים (צירים, תוויות, רקעים וכו'), ואם צריך, בוחרים את מידות הפיקסלים לרכיבים השונים (גודל התרשים , גודל המקרא וכן הלאה). כדאי לקרוא קודם את התיעוד הרלוונטי של סוג התרשים, אחרת חוויה מתסכלת. - יצירה ועיצוב של נתוני תרשים. הנתונים מצוינים באמצעות הפרמטר
chd. צריך לבחור את הפורמט שבו ייעשה שימוש בנתונים שלכם:- בחירה של פורמט נתונים. אפשר להשתמש בפורמט טקסט פשוט בשביל נתוני התרשימים. הפורמט הזה קל לקריאה, אבל תופס יותר מקום לשליחה, או להשתמש באחד מסוגי הקידוד, שקטן יותר לשליחה, אבל מגביל את טווח הערכים שאפשר לשלוח.
- מחליטים אם להתאים את הנתונים לתרשים. פורמטים שונים תומכים בטווחי ערכים שונים. כדאי להתאים את קנה המידה של הנתונים כך שיכלול את טווח הערכים המלא המותר לפי הפורמט, כדי שההבדלים יהיו ברורים יותר. אפשר לעשות זאת על ידי התאמת הנתונים לפורמט הנתונים שבו משתמשים. לחלופין, אפשר להשתמש בעיצוב טקסט עם התאמה אישית של קנה המידה.
- מקודדים את הנתונים לפי הצורך. אם בחרת פורמט מקודד, אנחנו מציעים קוד JavaScript כדי לעזור עם סוגי קידוד אחרים.
- מציינים את גודל התרשים. גודל התרשים מצוין באמצעות הפרמטר
chs. במסמכי העזרה של הפורמט והערכים המקסימליים. - מוסיפים עוד פרמטרים. בתיעוד של כל תרשים מפורטים הפרמטרים האופציונליים הזמינים. האפשרויות הנפוצות כוללות תוויות, כותרות וצבעים. לתשומת ליבכם: כל טקסט של תווית או כותרת חייב להיות בקידוד UTF-8. חשוב לזכור שפרמטרים רבים מאפשרים להזין מספר ערכים. לדוגמה, הפרמטר
chmמאפשר להוסיף צורה בנקודת נתונים אחת בתרשים. אפשר להוסיף צורות במספר נקודות על הגרף באמצעות הפרמטרchm, אבל לשם כך לא מציינים את הפרמטרchmכמה פעמים בכתובת ה-URL (לדוגמה, WRONG:chm=square&chm=circle&chm=triangle). במקום זאת, בפרמטרים שמקבלים מספר ערכים נעשה שימוש במפריד, כמו פסיק או קו אנכי, בין ערכים מרובים באותו פרמטר. עבורchm, זה סרגל, כך שיופיע משהו כזה: RIGHT:chm=square|circle|triangle. אפשר לעיין בפרטים של כל פרמטר כדי ללמוד איך לציין כמה פרמטרים. - יוצרים את המחרוזת של כתובת ה-URL. כתובת ה-URL מתחילה ב-
https://chart.googleapis.com/chart?ואחריה מופיעים כל הפרמטרים הנדרשים (cht,chd,chs) והאופציונליים. הערה: אם כתובת ה-URL משמשת אותך בתג<img>, צריך לשנות את כל התווים ב-&ל-&בקישור. לדוגמה:<img src="https://chart.googleapis.com/chart?chs=250x100&chd=t:60,40&cht=p3&chl=Hello|World" />. - כדי לקבל את התמונה, משתמשים בשיטת GET או ב-POST. אפשר להשתמש בפונקציית GET. כשמקלידים את כתובת ה-URL ישירות בדפדפן או משתמשים בה בתג
<img>. עם זאת, כתובות ה-URL מוגבלות לאורך של 2K, כך שאם יש לך יותר נתונים מכך או אם יש לך טעם של דם, מומלץ להשתמש ב-POST במקום זאת, כפי שמתואר כאן. - יצירת אזורים שניתן ללחוץ עליהם. אפשר ליצור מפת תמונה לתרשים שתאפשר להוסיף היפר-קישורים או רכיבי לחיצה לרכיבים ספציפיים בתרשים. פרטים נוספים זמינים במאמר יצירת מפת תמונה של תרשים.
מילון מונחים של התרשים
הנה כמה מונחים חשובים שבהם אנו משתמשים במסמך זה:
- סדרה
- קבוצה קשורה של נתונים בתרשים.
ההגדרה של סדרה תלויה בסוג התרשים: בתרשים קו, סדרה
היא קו אחד. בתרשים עוגה, כל רשומה היא פרוסה
וכל הפרוסות ביחד הן סדרה. בתרשים עמודות, סדרה מתייחסת לכל העמודות מאותה קבוצת נתונים. סדרות שונות מקובצות זו לצד זו או מוערמות זו על גבי זו, בהתאם לסוג של תרשים העמודות. בתרשים הבא מוצג
תרשים עמודות מקובץ עם שתי סדרות, אחת בכחול כהה והשנייה תכלת:
- תוויות ציר
- ערכים מספריים או ערכי טקסט לאורך כל ציר. בתרשים הקודם נבחרו התוויות 'ינו', 'פברואר', 'מרץ',
'0', '50', '100'.
רכיבים בתרשים
הנה כמה מהרכיבים של התרשים:
- אזור התרשים
- האזור שבו מוצגת אומנות הסדרה. פרטים נוספים זמינים בסרגל הצד 'רכיבי תרשים'.
- מקרא
- אזור קטן בתרשים שבו מתוארת הסדרה. בתרשים שלמעלה, זה הקטע עם 'חתולים' ו'כלבים'.
- פרמטר
- צמד key=value שנמצא בשימוש בכתובת ה-URL. לדוגמה:
chxt=x, כאשרchxtהוא שם הפרמטר ו-xהוא ערך הפרמטר. - GET ופרסום
- יש שתי שיטות לשליחת
כתובת ה-URL של התרשים. תהליך GET מתבצע בדרך כלל על ידי הקלדת כתובת URL בדפדפן, או על ידי הפיכתה למקור של תג
<img>. הביצוע של בקשות POST הוא מורכב יותר, אבל הן יכולות לכלול הרבה יותר נתונים. הסיבה העיקרית לשימוש ב-POST במקום ב-GET היא שבקשת POST יכולה להימשך הרבה יותר נתונים מאשר בקשת GET (16,000 תווים לעומת 2,000 תווים). מידע על POST זמין כאן. - תו צינור
- התו
|, המשמש לעיתים קרובות בתור ערך פרמטר delimiter, כלומר, תו לפיצול של כמה ערכים. פסיקים וסימני אמפרסנד (&) משמשים גם כמפרידים בכתובת ה-URL של התרשים. - תרשימים מורכבים
- תרשים שהוא שילוב של שני סוגי תרשימים שונים: לדוגמה, תרשים עמודות עם קו או תרשים קו עם סמני פמוט. מידע נוסף זמין בתרשימים מורכבים.
אופטימיזציות
אחרי שלמדתם את היסודות של יצירת תרשים, הנה כמה פעולות לאופטימיזציה שתוכלו להשתמש בהן.
שימוש ב-POST
כתובות ה-URL מוגבלות לאורך של 2K, כך שאם יש בתרשים שלך יותר נתונים, יהיה עליך להשתמש ב-POST במקום ב-GET, כפי שמתואר כאן. הפונקציה GET מתבצעת כשמקלידים
את כתובת ה-URL של התרשים בסרגל הכתובות של הדפדפן, או משתמשים בה כמקור של רכיב <img>
בדף אינטרנט. כדי להשתמש ב-POST צריך להוסיף תכנות בשפה אחרת,
כמו PHP או PERL.
יצירת תרשימים ב-JavaScript
אפשר להשתמש ב-Google Vision API כדי ליצור תרשימי תמונה. Google Vision API הוא ממשק API מבוסס JavaScript, שמספק כלים ליצירת נתונים, לסינון ולטיפול בנתונים, או לשליחת שאילתות לגיליונות אלקטרוניים של Google או לאתרים אחרים כדי לחפש נתונים. אפשר להשתמש ב-Vision API כדי ליצור את הנתונים, ולאחר מכן לבקש ממנו להפעיל את Image chart API כדי לעבד את התרשים בדף. מידע נוסף זמין במסמכי התיעוד הכלליים של תרשים התמונות או בגלריית התצוגה החזותית כדי לראות תרשימים של Google שסומנו (תמונה).