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

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

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

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