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

מפתחים באזור הכלכלי האירופי (EEA)

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

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

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

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

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

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

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