בקשה ותגובה של Street View

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

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

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

פרמטרים נדרשים

למשל:

  • השדה location יכול להיות מחרוזת טקסט (כמו Chagrin Falls, OH) או קבוצה של קואורדינטות רוחב וקו אורך (40.457375,-80.009353), וצריכים לקבוע לו קידוד URL. לכן, לפני שליחת הבקשה, צריך להמיר כתובות כמו 'City Hall, New York, NY' ל-'City+Hall,New+York,NY'. Street View Static API מתמקם בתמונה הפנורמית הקרובה ביותר למיקום. כשמספקים מחרוזת טקסט של כתובת, ה-API עשוי להשתמש במיקום מצלמה אחר כדי להציג טוב יותר את המיקום שצוין. כשמציינים קואורדינטות של קווי אורך ורוחב, ה-API מחפש תמונה הקרובה ביותר למיקום ברדיוס של 50 מטרים. מכיוון שתמונות Street View מתעדכנות מדי פעם, ויכול להיות שהתמונות צולמו מזוויות שונות במקצת בכל פעם, יכול להיות ש-location יעבור לתמונה פנורמית אחרת כשהתמונות יתעדכנו.

או:

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

וגם:

  • size מציין את גודל הפלט של התמונה בפיקסלים. הגודל מצוין כ-{width}x{height}. לדוגמה, size=600x400 מחזיר תמונה ברוחב 600 פיקסלים ובגובה 400 פיקסלים.
  • key מאפשר לכם לעקוב אחרי השימוש של האפליקציה ב-API במסוף Google Cloud, ולוודא ש-Google תוכל ליצור איתכם קשר לגבי האפליקציה במקרה הצורך. מידע נוסף זמין במאמר קבלת מפתח וחתימה.

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

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

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

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

פרמטרים אופציונליים

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

    הערה: לקוחות לשעבר של מינוי Premium בפלטפורמה של מפות Google צריכים לשלוח חתימה דיגיטלית. מידע נוסף על פרמטרים של אימות ללקוחות עם מינוי Premium

  • heading מציין את כיוון המצפן של המצלמה. הערכים הקבילים הם מ-0 עד 360 (שני הערכים מציינים צפון, כאשר 90 מציין מזרח ו-180 דרום). אם לא מציינים כיוון, מחושב ערך שמכוון את המצלמה ל-location שצוין, מהנקודה שבה צולמה התמונה הקרובה ביותר.
  • fov (ברירת המחדל היא 90) קובע את שדה הראייה האופקי של התמונה, שמצוין במדד של מעלות, עם ערך מקסימלי של 120. כשמדובר בחלון תצוגה בגודל קבוע, כמו תמונה ב-Street View בגודל מוגדר, שדה הראייה מייצג למעשה זום, כאשר מספרים קטנים יותר מציינים רמת זום גבוהה יותר.


    צילום מסך של שדה ראייה רחב, שבו מוצגים התקרה, הקירות, הרצפה וחלון של אקווריום. צילום מסך של שדה ראייה של צילום מקרוב, שבו מוצגים פרטים מוגדלים של תמונת Street View בתוך אקווריום.
    (שמאל: fov=120, ימין: fov=20)

  • pitch (ברירת המחדל היא 0) מציין את הזווית כלפי מעלה או כלפי מטה של המצלמה ביחס לרכב של Street View. בדרך כלל הוא אופקי, אבל לא תמיד. ערכים חיוביים מטים את המצלמה כלפי מעלה (עם 90 מעלות שמציינות ישירות למעלה), וערכים שליליים מטים את המצלמה כלפי מטה (עם -90 שמציין ישירות למטה).
  • radius (ברירת המחדל היא 50) מגדיר את הרדיוס, שמצוין במטרים, שבו יתבצע חיפוש של תמונה פנורמית שממוקדת בקו הרוחב ובקו האורך שצוינו. הערכים החוקיים הם מספרים שלמים חיוביים.
  • השדה return_error_code מציין אם ה-API צריך להחזיר קוד שגיאה כשלא נמצאת תמונה (404 NOT FOUND) או בתגובה לבקשה לא חוקית (400 BAD REQUEST). הערכים החוקיים הם true ו-false. אם הערך מוגדר ל-true, תוחזר הודעת שגיאה במקום התמונה האפורה הגנרית. כך לא תצטרכו לבצע קריאה נפרדת כדי לבדוק את זמינות התמונה.
  • source (ברירת המחדל היא default) מגביל את החיפושים ב-Street View למקורות נבחרים. הערכים התקינים הם:
    • default משתמש במקורות ברירת המחדל של Street View. החיפושים לא מוגבלים למקורות ספציפיים.
    • outdoor מגביל את החיפושים לאוספים של אירועים בחוץ. אוספים של פריטים פנימיים לא נכללים בתוצאות החיפוש. שימו לב: יכול להיות שלא יהיו תמונות פנורמיות של חוץ במיקום שציינתם. חשוב לזכור שהחיפוש מחזיר רק תמונות פנורמיות שבהן אפשר לקבוע אם הן צולמו בתוך מבנה או בחוץ. לדוגמה, תמונות PhotoSphere לא מוצגות כי לא ידוע אם הן צולמנו בתוך הבית או בחוץ.

זוהי דוגמה לבקשה.

https://maps.googleapis.com/maps/api/streetview?size=600x300&location=46.414382,10.013988&heading=151.78&pitch=-0.76&key=YOUR_API_KEY&signature=YOUR_SIGNATURE
צילום מסך של תמונה בתצוגת מיקום ברמת הרחוב, שבה מוצגות פסי רכבת חשמליים.

אין תמונות זמינות

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

צילום מסך של התמונה הגנרית שמוצגת כשאין תמונות זמינות למיקום שצוין. הרקע חום בהיר, ומוצג בו הטקסט 'מצטערים, אין לנו תמונות כאן'.
איור: תמונה גנרית שמוצגת כשאין תמונות זמינות למיקום שצוין.

הצגת תמונות תקינות בלבד

כדי להימנע מהצגת התמונה הגנרית ולהבטיח שבדף האינטרנט יוצגו רק תמונות תקינות של Street View Static API, כדאי לפעול לפי ההצעות הבאות:

  • מגדירים את הפרמטר return_error_code לערך true. אם אין תמונה זמינה למיקום שצוין, המערכת תגרום ל-Street View Static API להחזיר את השגיאה 404 NOT FOUND במקום התמונה האפורה הגנרית.
  • לפני שליחת הבקשה, כדאי לבקש מטא-נתונים של תמונות Street View כדי לבדוק אם יש תמונות זמינות של המיקום שציינתם.