בקשה ותגובה של 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.