מטא-נתונים של תמונות Street View

מבוא

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

הערה: הערך בשדה התאריך עשוי להשתנות:

• בשדה התאריך יכולה להיות רמת פירוט שונה של תמונות פנורמה שונות. לדוגמה, בחלק מהפנורמות יש שדה תאריך שמכיל שנה וחודש, ובחלקן יש רק את השנה.
• שדה התאריך יושמט אם אין נתונים זמינים.

בקשות למטא-נתונים של Street View Static API זמינות ללא תשלום. כאשר מבקשים מטא-נתונים, המערכת לא צורכת מכסה. המכסה מנוצלת רק כשטוענים תמונה באמצעות Street View Static API.

כששולחים בקשות למטא-נתונים של תמונות Street View, התמונות הפנורמיות מדויקות בטווח של 50 מטר.

גישה למטא-נתונים של תמונות

בקשת מטא-נתונים של תמונה של Street View היא כתובת URL מסוג HTTP בצורה הבאה:

https://maps.googleapis.com/maps/api/streetview/metadata?parameters

הערה: הפרוטוקול https:// נדרש לבקשות למטא-נתונים.

כרגיל בכתובות URL, כל הפרמטרים מופרדים באמצעות תו האמפרסנד (&).

הפרמטרים הנדרשים לבקשות למטא-נתונים

הבקשות למטא-נתונים מקבלות את אותם פרמטרים של כתובות URL שמקבלים בקשות לתמונות ב-Street View Static API, אבל נדרשים רק הפרמטרים הבאים:

יש שתי אפשרויות:

• location - יכול להיות מחרוזת טקסט (כמו Chagrin Falls, OH) או צמד של קווי אורך ורוחב שמופרדים בפסיקים (40.457375,-80.009353).

או:

• pano - מזהה פנורמה ספציפי. תמונות פנורמה עשויות לשנות את המזהים עם הזמן, לכן אל תשמרו את המזהה. במקום זאת, שמרו את הכתובת או את הקואורדינטות של קווי האורך והרוחב כדי שתוכלו לרענן את מזהה הפנורמה. לפרטים נוספים, ראו רענון של מזהי פנורמה שנמחקו.

וגם:

• key ו-signature — מפתח ה-API נדרש כדי לאמת את הבקשה. במקרים מסוימים נדרשת גם חתימה דיגיטלית, ותמיד מומלץ להשתמש בה. למידע נוסף תוכלו לקרוא את המאמר קבלת מפתח וחתימה.

בקשת המטא-נתונים שלך, עם פרמטרים נדרשים בלבד, נראית כך:

https://maps.googleapis.com/maps/api/streetview/metadata?location=&key=YOUR_API_KEY&signature=

או כך:

https://maps.googleapis.com/maps/api/streetview/metadata?pano=&key=YOUR_API_KEY&signature=

רענון מזהי הפנורמה שנמחקו

אם תנסו לאחזר מזהה פנורמה ולקבל ZERO_RESULTS או ללא ערך, מזהה הפנורמה נמחק וצריך לרענן אותו.

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

2. כשתזהו שמזהה הפנורמה השתנה, השתמשו בכתובת המיקום או בקואורדינטות של קווי האורך והרוחב המקוריים כדי לחפש שוב את הפנורמות הקרובות ביותר לאותו מיקום ולקבל מזהה פנורמה חדש.

שימו לב: מכיוון שהתמונות ב-Street View עוברות רענון מעת לעת, וייתכן שהתמונות מצולמות במיקומים מעט שונים בכל פעם, לכן מזהה פנורמה נתון עשוי להצמיד תמונת פנורמה אחרת לאחר עדכון של תמונות או מזהה פנורמה.

פרמטרים אופציונליים לבקשות למטא נתונים

ניתן לכלול את הפרמטרים הבאים בבקשת המטא-נתונים: size, heading, fov ו-pitch. שימו לב שהפרמטרים האלה לא משפיעים על הנתונים של תמונת הפנורמה או של הפנורמה שמופיעה. ה-API מאפשר לכלול את אותם הפרמטרים שכלולים בבקשת תמונה, כדי להקל על היצירה של בקשה למטא-נתונים שקשורה לבקשה ספציפית לתמונות, אבל בבקשות למטא-נתונים ה-API מתעלם מהפרמטרים האופציונליים ומהערכים שלהם. למידע נוסף על השימוש בפרמטרים האלה, כדאי לעיין במדריך למפתחים בנושא Street View Static API.

פורמט התשובה

תגובות למטא-נתונים מוחזרות בפורמט JSON בלבד.

דוגמאות

דוגמה 1: נמצאה פנורמה

כתובות ה-URL הבאות מבקשות בהצלחה את המטא-נתונים והתמונה של אותה פנורמה.

בקשה ותשובה למטא-נתונים

https://maps.googleapis.com/maps/api/streetview/metadata?size=600x300&location=eiffel%20tower,%20paris,%20france&heading=-45&pitch=42&fov=110&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

{
   "copyright" : "© 2017 Google",
   "date" : "2016-05",
   "location" : {
      "lat" : 48.85783227207914,
      "lng" : 2.295226175151347
   },
   "pano_id" : "tu510ie_z4ptBZYo2BGEJg",
   "status" : "OK"
}

בקשה לתמונות ותשובה, שבהן צפויה התמונה החסרה.

https://maps.googleapis.com/maps/api/streetview?size=600x300&location=eiffel%20tower,%20paris,%20france&heading=-45&pitch=42&fov=110&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

דוגמה 2: לא נמצאה פנורמה

כתובות ה-URL הבאות מבקשות את המטא-נתונים ואת התמונה של תמונת פנורמה שלא ניתן היה למצוא במיקום שצוין או קרוב אליו.

בקשה ותשובה למטא-נתונים

https://maps.googleapis.com/maps/api/streetview/metadata?size=600x300&location=78.648401,14.194336&fov=90&heading=235&pitch=10&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

{
   "status" : "ZERO_RESULTS"
}

בקשה ותשובה לתמונות

https://maps.googleapis.com/maps/api/streetview?size=600x300&location=78.648401,14.194336&fov=90&heading=235&pitch=10&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

קודי סטטוס

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

סטטוס	תיאור
"OK"	מציין שלא התרחשו שגיאות; נמצאה פנורמה ומוחזרים המטא-נתונים.
"ZERO_RESULTS"	מציין שלא ניתן היה למצוא פנורמה בקרבת המיקום שצוין. תגובה כזו יכולה לקרות אם תספקו מזהה פנורמה לא קיים או לא חוקי. ראו [רענון של מזהי פנורמה שנמחקו](#refresh-pano).
"NOT_FOUND"	זה מציין שלא ניתן היה למצוא את מחרוזת הכתובת שצוינה בפרמטר location. יכול להיות שההודעה הזו תופיע אם ניתנה כתובת שלא קיימת.
"OVER_QUERY_LIMIT"	הערך הזה מציין שחרגתם מהמכסה היומית או מהמכסה לשנייה ב-API הזה.
"REQUEST_DENIED"	מצביע על כך שהבקשה שלך נדחתה. ההודעה הזאת יכולה להופיע אם לא אישרתם את הבקשה, או אם ה-API הסטטי של Street View לא הופעל בפרויקט במסוף Google Cloud שמכיל את מפתח ה-API שלכם.
"INVALID_REQUEST"	בדרך כלל מציין שהפרמטרים של השאילתה (כתובת, קואורדינטות של קווי אורך ורוחב או רכיבים) חסרים.
"UNKNOWN_ERROR"	זה מציין שלא ניתן היה לעבד את הבקשה עקב שגיאה בחיבור לשרת. בדרך כלל מדובר בבעיה זמנית. ניסיון חוזר של הבקשה עשוי להתבצע בהצלחה.

מידע נוסף

למידע נוסף על השימוש ב-Street View Static API או במוצרים אחרים של Google Maps API, מומלץ לקרוא את דף התמיכה של ה-API של מפות Google.