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

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

בקשה ל-Street View Image היא כתובת 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. אם אין תמונה זמינה למיקום שצוין, ה-API הסטטי של Street View יחזיר את השגיאה 404 NOT FOUND במקום התמונה האפורה הגנרית.
  • לפני ששולחים בקשה, שולחים בקשה למטא-נתונים של תמונות Street View כדי לבדוק אם יש תמונות זמינות למיקום שצוין.