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

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

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

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

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

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