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

בקשת תמונה של 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". ה-API הסטטי של Street View מבצע הצמדה לתמונת הפנורמה הקרובה ביותר למיקום. כשמציינים מחרוזת טקסט של כתובת, ה-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 Premium צריכים לחתום על החתימה הדיגיטלית. למידע נוסף על פרמטרים של אימות ללקוחות של מינוי 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 מגביל את החיפושים לאוספים בחוץ. אוספים מקורים לא נכללים בתוצאות החיפוש. שימו לב: ייתכן שלא קיימות תמונות פנורמיות בחוץ במיקום שצוין. כמו כן, חשוב לזכור שהחיפוש מחזיר תמונות פנורמה רק כאשר ניתן לקבוע אם התמונות צריכות להיות בפנים או בחוץ. לדוגמה, תמונות פנורמיות ב-360° לא מוחזרות כי לא ידוע אם הם בפנים או בחוץ.

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

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 לא נמצא במקום התמונה האפורה, אם אין תמונה זמינה במיקום שצוין.
  • מבקשים מטא-נתונים של תמונות Street View על מנת לבדוק אם יש תמונות במיקום שצוין, לפני שליחת הבקשה.