ממשקי ה-API הסטטיים של פלטפורמת מפות Google הם אוסף של ממשקי HTTP לשירותי Google, שמאפשרים ליצור תמונות שאפשר להטמיע ישירות בדף האינטרנט.
במדריך הזה מתוארות כמה שיטות נפוצות שיעזרו לכם להגדיר את הבקשות של התמונות ולעבד את התשובות מהשירות. במדריך למפתחים תוכלו למצוא את המסמכים המלאים של Maps Static API.
מהו Static Web API?
ממשקי ה-API הסטטיים של Google Maps Platform לאינטרנט מאפשרים להטמיע תמונה של מפות Google בדף האינטרנט שלכם בלי צורך ב-JavaScript או בטעינה דינמית של דפים. ממשקי ה-API הסטטיים של האינטרנט יוצרים תמונה על סמך פרמטרים של כתובות URL שנשלחים באמצעות בקשת HTTPS רגילה.בקשה אופיינית ל-Maps Static API בדרך כלל נראית כך:
https://www.googleapis.com/staticmap/z/x/y?parameters
הערה: כל האפליקציות של Maps Static API מחייבות אימות. מידע נוסף על פרטי כניסה לאימות
גישה ל-SSL/TLS
צריך להשתמש ב-HTTPS בכל הבקשות לפלטפורמה של מפות Google שמשתמשות במפתחות API או מכילות נתוני משתמשים. יכול להיות שנדחה בקשות שנשלחות ב-HTTP ומכילות מידע אישי רגיש.
יצירת כתובת URL תקינה
יכול להיות שתחשובו שכתובת URL "תקינה" היא מובנת מאליו, אבל זה לא בדיוק המצב. לדוגמה, כתובת URL שמזינים בסרגל הכתובות בדפדפן עשויה להכיל תווים מיוחדים (למשל "上海+中國"). הדפדפן צריך לתרגם את התווים האלה באופן פנימי לקידוד אחר לפני ההעברה.
באופן דומה, כל קוד שיוצר או מקבל קלט ב-UTF-8 עשוי להתייחס לכתובות URL עם תווים ב-UTF-8 כ'תקינות', אבל יהיה עליו גם לתרגם את התווים האלה לפני השליחה שלהם לשרת אינטרנט.
התהליך הזה נקרא
קידוד כתובות 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 שמקבלים מהקלדה של משתמש. לדוגמה, משתמש יכול להזין כתובת כמו 'רחוב 5 ו-Main'. באופן כללי, צריך ליצור את כתובת ה-URL מהחלקים שלה, ולתייחס לכל קלט של משתמש בתור תווים מילוליים.
בנוסף, כתובות URL מוגבלות ל-16,384 תווים בכל שירותי האינטרנט של הפלטפורמה של מפות Google וממשקי ה-API הסטטיים של האינטרנט. ברוב השירותים, מגבלת התווים הזו תהיה גדולה מדי. עם זאת, חשוב לזכור שלשירותים מסוימים יש כמה פרמטרים שעשויים לגרום לכתובות URL ארוכות.