ממשקי ה-API הסטטיים לאינטרנט בפלטפורמה של מפות Google הם אוסף של ממשקי HTTP לשירותי Google. ממשקי ה-API האלה יוצרים תמונות שאפשר להטמיע ישירות בדף האינטרנט.
במדריך הזה מתוארות כמה שיטות נפוצות שיכולות לעזור להגדרת בקשות תמונה ועיבוד תשובות של שירות. לתיעוד המלא של Maps Static API, עיינו במדריך למפתחים.
מה זה Static Web API?
ממשקי ה-API הסטטיים לאינטרנט בפלטפורמה של מפות Google מאפשרים להטמיע תמונה של מפות Google בדף האינטרנט, ללא צורך ב-JavaScript או בטעינה דינמית של דף. ממשקי ה-API הסטטיים לאינטרנט יוצרים תמונה על סמך פרמטרים של כתובות URL שנשלחים באמצעות בקשת HTTPS רגילה.בקשה אופיינית ל-Static API של מפות Google היא בדרך כלל בתבנית הבאה:
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 צריכות להתאים לתחביר שצוין במפרט Uniform Resource Identifier (URI). בפועל, פירוש הדבר הוא שכתובות ה-URL חייבות להכיל רק קבוצת משנה מיוחדת של תווי ASCII: הסמלים האלפאנומריים המוכרים וכמה תווים שמורים לשימוש כתווי בקרה בכתובות ה-URL. הטבלה הבאה מסכמת את התווים הבאים:
| הגדרה | תווים | שימוש בכתובת URL |
|---|---|---|
| אלפאנומרי | a b c d 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 3 8 5 2 | מחרוזות טקסט, שימוש בסכימה (http), יציאה (8080) וכו'. |
| לא שמור | - _ . ~ | מחרוזות טקסט |
| בוצעה הזמנה | ! * ' ( ) ; : @ & = + $ , / ? % # [ ] | תווי בקרה ו/או מחרוזות טקסט |
כשיוצרים כתובת URL חוקית, צריך לוודא שהיא מכילה רק את התווים שמופיעים בסיכום של הטבלה 'תווים חוקיים של כתובת URL'. יצירה של כתובת URL לשימוש בקבוצת התווים הזו בדרך כלל מובילה לשתי בעיות, אחת של השמטה ואחת להחלפה:
- התווים שבהם ברצונך לטפל קיימים מחוץ לקבוצה שלמעלה. לדוגמה, תווים בשפות זרות כמו
上海+中國צריכים להיות מקודדים באמצעות התווים שלמעלה. בדרך כלל, רווחים (אסורים בכתובות URL) מיוצגים באמצעות סימן החיבור'+'. - תווים קיימים בקבוצה שלמעלה כתווים שמורים,
אבל צריך להשתמש בהם באופן מילולי.
לדוגמה, נעשה שימוש ב-
?בתוך כתובות URL כדי לציין את ההתחלה של מחרוזת השאילתה. אם רוצים להשתמש במחרוזת "? ובמסתוריות", צריך לקודד את התו'?'.
כל התווים לקידוד כתובת 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 שמקבלים מקלט של משתמשים. לדוגמה, משתמש יכול להזין כתובת כ"רחוב ראשי וחמישי". באופן כללי, מומלץ ליצור את כתובת ה-URL מהחלקים שלה, ולהתייחס לכל קלט של משתמש כאל תווים מילוליים.
בנוסף, כתובות ה-URL מוגבלות ל-16,384 תווים בכל שירותי האינטרנט של הפלטפורמה של מפות Google וממשקי ה-API הסטטיים לאינטרנט. ברוב השירותים, כמעט שלא תתקשו למגבלת התווים הזו. עם זאת, שימו לב שלשירותים מסוימים יש כמה פרמטרים שעשויים ליצור כתובות URL ארוכות.