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

מבוא

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

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

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

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

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

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

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

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

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

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

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

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

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

• 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 מתעלם מהפרמטרים האופציונליים ומהערכים שלהם. למידע על השימוש בפרמטרים האלה, ראו מדריך למפתחים של ממשקי API סטטיים של Street View.

פורמט התשובה

תגובות של מטא-נתונים מוחזרות בפורמט 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"	מציין שהבקשה שלך נדחתה. ההודעה הזו יכולה להופיע אם לא אישרתם את הבקשה, או אם Street View Static API לא הופעל בפרויקט במסוף Google Cloud שמכיל את מפתח ה-API שלכם.
"INVALID_REQUEST"	באופן כללי מציינת שהפרמטרים של השאילתה (כתובת, קואורדינטות של קו רוחב וקו אורך או רכיבים) חסרים.
"UNKNOWN_ERROR"	מציין שלא ניתן היה לעבד את הבקשה עקב שגיאה בחיבור לשרת. בדרך כלל הבעיה הזו זמנית. אם תנסו שוב, יכול להיות שהבקשה תבוצע בהצלחה.

מידע נוסף

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