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