הודעות שגיאה ב-Maps Static API

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

בקשות לא תקינות

במקרה של בקשה לא חוקית, ה-Maps Static API מחזיר קוד סטטוס HTTP‏ 4xx והודעה שמתארת את הבעיה. בהמשך מפורטות דוגמאות לתנאי שגיאה כאלה. הערה: זוהי רשימה חלקית בלבד של השגיאות האפשריות. כדי לקבל פרטים על בעיות ספציפיות, צריך לבדוק את קוד השגיאה ואת ההודעה בפועל שמוחזרים על ידי ה-API.

דוגמה לתנאי שגיאה קוד סטטוס
הבקשה כוללת פרמטר לא חוקי או שחסרה בה פרמטר חובה. לדוגמה, הפרמטר size לא נמצא בטווח הצפוי של ערכים מספריים, או שהוא חסר בבקשה. 400 BAD REQUEST
מפתח ה-API שכלול בבקשה לא תקין. 403 FORBIDDEN

שגיאות שמונעות את הצגת המפה

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

תמונה של שגיאה מוצגת במקום מפה
איור: תמונה של שגיאה מוצגת במקום מפה

אם משתמשים ב-Maps Static API ללא מפתח API, או אם החיוב לא מופעל בחשבון, יוצג בדף תמונה של שגיאה במקום מפה, עם קישור שמציין את סוג השגיאה. לדוגמה: ‎"g.co/staticmaperror/key"‎.

שגיאות ללא מפתחות ופתרונות
שגיאה בנושא מגבלות שימוש: חרגתם מהמגבלה היומית של טעינת המפות אתם משתמשים ב-Maps Static API ללא מפתח API. כדי לפתור את הבעיה:
  1. קבלת מפתח API
  2. הפעלת החיוב
  3. חתימה על כתובת ה-URL
שגיאה בקשר למגבלות השימוש: כתובות ה-URL של הבקשות חסרות את החתימה הדיגיטלית בבקשה שלך חסר חתימה דיגיטלית (חובה). כדי לפתור את הבעיה, צריך לחתום על כתובת ה-URL.

אזהרות

בתנאים מסוימים של שגיאה, ה-API מחזיר מפה אבל יכול להיות שחסר בה מידע מסוים. במקרה כזה, מתקיימים שני תנאים כדי להודיע לכם על האזהרה.

  • אחת מהן היא שהמפה מוצגת, אבל עם סרגל שגיאה צהוב שמופיע מעל המפה עם הטקסט 'שגיאה במפה: g.co/staticmaperror'.
  • שתיים, ה-API מחזיר אזהרה בצורת כותרת HTTP בשם X-Staticmap-API-Warning.

לדוגמה, כתובת ה-URL הבאה מכילה ערך לא צפוי בפרמטר markers:

https://maps.googleapis.com/maps/api/staticmap?center=Williamsburg,Brooklyn,NY&zoom=13&scale=1&size=400x400&markers=sdgaags&key=YOUR_API_KEY

ה-API מחזיר מפה, אבל מוצגת עמודת שגיאה צהובה מעל התמונה עם הכיתוב 'שגיאה במפה: g.co/staticmaperror':

המפה מוצגת, אבל עם השגיאה 'מפה: g.co/staticmaperror'

ה-API מחזיר גם את כותרת ה-HTTP הבאה:

X-Staticmap-API-Warning:Error geocoding: marker 1

בטבלה הבאה מתוארים האזהרות שה-API עשוי להנפיק ככותרות HTTP:

אזהרות בכותרות של X-Staticmap-API-Warning
Error geocoding: [center, ][marker #number, ][visible #num, ][path #num, ]* אירעה שגיאה בניסיון לשייך את הבקשה למיקום גיאוגרפי. יש וריאציות רבות של ההודעה הזו, בהתאם לאלמנט שבו גיאוקוד נכשל (מרכז, סמן, גלוי או נתיב) ומספר הרכיבים שנכשלו. דוגמה לאזהרה הזו היא הערך X-Staticmap-API-Warning:Error geocoding: marker 1, כפי שמוצג בדוגמה שלמעלה.
Too many geocoded markers requested (max is 15). בבקשה צוין מספר גדול מהמספר המקסימלי המותר של סמנים עם כתובת שניתנת לקריאה על ידי בני אדם. המספר המקסימלי הוא 15. חשוב לציין שהמגבלה הזו חלה רק על סמנים שצוינו ככתובת שאנשים יכולים לקרוא ושצריך להמיר לקואורדינטות. הוא לא חל על סמנים שצוינו באמצעות קואורדינטות של קו אורך וקו רוחב.
Too many geocoded polyline vertices requested (max is 15). בבקשה צוין מספר גדול יותר מהמספר המקסימלי המותר של קווים פוליגונליים עם כתובת שניתנת לקריאה על ידי בני אדם. המספר המקסימלי הוא 15. חשוב לציין שהמגבלה הזו חלה רק על קווים פוליגונליים עם קודקודים שצוינו ככתובות שניתנות לקריאה על ידי בני אדם, שדורשות גיאוקודינג. הוא לא חל על קווים פוליגונליים שצוינו באמצעות קואורדינטות של קו אורך וקו רוחב.

אפשר לראות את האזהרות בכותרת ה-HTTP במסוף DevTools של Chrome, במסוף האינטרנט של Firefox או בכלים מקבילים אחרים בדפדפן.