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

    הערה: לקוחות לשעבר בתוכנית הפרימיום של הפלטפורמה של מפות 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 יש הגבלה על החיפושים לאוספים בחוץ. אוספים פנימיים לא נכללים בתוצאות החיפוש. לתשומת ליבך, יכול להיות שלא קיימות תמונות פנורמיות בחוץ במיקום שצוין. כמו כן, החיפוש מחזיר תמונות פנורמה רק כאשר ניתן לקבוע אם הן בתוך מבנים או בחוץ. לדוגמה, תמונות פנורמיות ב-360° לא מוחזרות כי לא ידוע אם הן בתוך מבנים או בחוץ.

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

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 כדי לבדוק אם יש תמונות זמינות במיקום שצוין לפני שליחת הבקשה.