שיטות מומלצות לשימוש ב-Maps Static API

ממשקי ה-API הסטטיים של האינטרנט ב-Google Maps Platform הם אוסף של ממשקי HTTP לשירותי Google, שמייצרים תמונות שאפשר להטמיע ישירות בדף האינטרנט.

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

מה זה API סטטי לאינטרנט?

ממשקי ה-API הסטטיים של Google Maps Platform מאפשרים להטמיע תמונה של מפות Google בדף אינטרנט בלי להשתמש ב-JavaScript או בטעינה דינמית של דפים. ממשקי ה-API של אתרים סטטיים יוצרים תמונה על סמך פרמטרים של כתובת URL שנשלחים באמצעות בקשת HTTPS רגילה.

בקשת API אופיינית ל-Maps Static API היא מהצורה הבאה:

  https://www.googleapis.com/staticmap/z/x/y?parameters

הערה: בכל האפליקציות של Maps Static API נדרשת אימות. מידע נוסף זמין במאמר בנושא פרטי אימות.

גישה ל-TLS

חובה להשתמש ב-HTTPS בכל הבקשות ל-Google Maps Platform שמשתמשות במפתחות API או מכילות נתוני משתמשים. יכול להיות שבקשות שמועברות באמצעות HTTP ומכילות מידע אישי רגיש יידחו.

יצירת כתובת URL תקינה

יכול להיות שאתם חושבים שכתובת URL 'תקינה' היא דבר ברור מאליו, אבל זה לא בדיוק המצב. לדוגמה, כתובת URL שמוזנת בסרגל הכתובות בדפדפן עשויה להכיל תווים מיוחדים (למשל, "上海+中國"). הדפדפן צריך לתרגם את התווים האלה באופן פנימי לקידוד אחר לפני השידור. באופן דומה, כל קוד שמייצר או מקבל קלט UTF-8 עשוי להתייחס לכתובות URL עם תווים בקידוד UTF-8 כאל כתובות 'תקינות', אבל הוא גם יצטרך לתרגם את התווים האלה לפני שהוא שולח אותם לשרת אינטרנט. התהליך הזה נקרא קידוד כתובות URL או קידוד באחוזים.

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

תווים מיוחדים

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

הגדרה	תווים	שימוש בכתובות URL
אלפאנומרי	a b c d e f g h i j k l m n o p q r s t u v w x y z A B C D E F G H I J K L M N O P Q R S T U V W X Y Z 0 1 2 3 4 5 6 7 8 9	מחרוזות טקסט, שימוש בסכימה (http), יציאה (8080) וכו'.
לא שמור	‪- _ . ~	מחרוזות טקסט
בוצעה הזמנה	! * ' ( ) ; : @ & = + $ , / ? ‫% # [ ]	תווי בקרה או מחרוזות טקסט

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

• יש תווים שרוצים לטפל בהם מחוץ לקבוצה שלמעלה. לדוגמה, תווים בשפות זרות כמו 上海+中國 צריכים להיות מקודדים באמצעות התווים שלמעלה. לפי מוסכמה נפוצה, רווחים (שאסור להשתמש בהם בכתובות URL) מיוצגים לעיתים קרובות גם באמצעות התו '+'.
• התווים האלה קיימים בסט שלמעלה כתווים שמורים, אבל צריך להשתמש בהם באופן מילולי. לדוגמה, התו ? משמש בכתובות URL כדי לציין את תחילת מחרוזת השאילתה. אם רוצים להשתמש במחרוזת '? and the Mysterions', צריך לקודד את התו '?'.

כל התווים שמיועדים לקידוד URL מקודדים באמצעות התו '%' וערך הקסדצימלי בן שני התווים שמתאים לתווים בקידוד UTF-8. לדוגמה, 上海+中國 ב-UTF-8 יותאם לקידודי התווים שמתאימים לכתובות URL באופן הבא: %E4%B8%8A%E6%B5%B7%2B%E4%B8%AD%E5%9C%8B. המחרוזת ? and the Mysterians תעבור קידוד כתובות URL כ-%3F+and+the+Mysterians או כ-%3F%20and%20the%20Mysterians.

תווים נפוצים שצריך לקודד

אלה כמה תווים נפוצים שצריך לקודד:

תו לא בטוח	ערך מקודד
רווח	%20
"	%22
<	%3C
>	%3E
#	%23
%	%25
|	%7C

לפעמים קשה להמיר כתובת URL שמתקבלת מקלט של משתמשים. לדוגמה, משתמש יכול להזין כתובת כ-"5th&Main St." באופן כללי, צריך ליצור את כתובת ה-URL מהחלקים שלה, ולהתייחס לכל קלט של משתמשים כאל תווים מילוליים.

בנוסף, כתובות URL מוגבלות ל-16,384 תווים בכל שירותי האינטרנט של Google Maps Platform ובממשקי API סטטיים לאינטרנט. ברוב השירותים, לא תגיעו למגבלת התווים הזו. עם זאת, חשוב לשים לב שלחלק מהשירותים יש כמה פרמטרים שיכולים לגרום לכתובות URL ארוכות.