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

  • ‫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.