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

מידע נוסף

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