אריחי Street View

אריחים ב-Street View דומים לאריחים דו-ממדיים אבל הם מכילים תמונות פנורמיות שצולמו ברמת הרחוב. באמצעות Street View אפשר לסייר באתרים מפורסמים בעולם, לראות פלאי טבע ולהיכנס למקומות כמו מוזיאונים, אצטדיונים, מסעדות או עסקים קטנים. נקודת הקצה הזו ב-API מעניקה גישה אל:

• קטעי Street View של מפות Google
• מטא-נתונים של Street View
• תמונות ממוזערות של Street View

אפשר לחבר יחד אריחי תמונות שצולמו מרמת הרחוב, כדי ליצור אפקט פנורמי אמיתי. ניתן לך גם להריץ שאילתה על עד 100 מזהים פנורמיים עבור קבוצה של מיקומים (כמו מסלול) ולקבל מטא-נתונים מפורטים יותר לגבי מיקום המצלמה.

יש צורך בצופה כדי לחבר יחד משבצות של Street View. לדוגמה, מציג הפנורמה המותאם אישית Street View.

טיפ: למידע נוסף, ראו Street View Static API ושירות Street View.

ברגע שיש לכם מפתח API, תוכלו לבצע את השלבים הבאים כדי לגשת לתמונות של Street View.

1. מקבלים אסימון סשן. חשוב לוודא שהערך של mapType מוגדר ל-streetview.

2. השתמשו באסימון הסשן כדי לקבל את המזהה הפנורמי (panoId) של מיקום גיאוגרפי אחד או יותר.

3. תוכלו להשתמש במזהי הפנורמות מהתגובה לחיפוש של תמונה פנורמית כדי לקבל:

   1. מטא-נתונים של Street View. אפשר גם לקבל מטא-נתונים של Street View על ידי העברת קבוצת קואורדינטות ורדיוס.

   2. תמונות ממוזערות של Street View.

   3. משבצות Street View.

הערה: חובה להציג פרטים על זכויות היוצרים בכל תמונת פנורמה של Street View. המחרוזת לתצוגה יכולה להשתנות בין תמונות פנורמה. לקבלת מידע על זכויות יוצרים, עליכם לבקש מטא-נתונים של Street View, ולאחר מכן תוכלו לעיין בשדה copyright של התשובה.

שיטות Street View

אפשר לגשת לתמונות ולמטא-נתונים של Street View באמצעות אחת מארבע השיטות הבאות.

שיטה	תיאור
https://tile.googleapis.com/v1/streetview/tiles	מחזירה את האריחים הספציפיים של Street View. אפשר לאחזר משבצות של Street View בשש רמות של מרחק מהתצוגה: מ-512 פיקסלים ועד 13,312 פיקסלים.
https://tile.googleapis.com/v1/streetview/panoIds	מאפשר חיפוש בכמות גדולה של עד 100 מיקומים. מחזירה מזהים פנורמיים עבור כל המיקומים עם תמונות.
https://tile.googleapis.com/v1/streetview/thumbnail	מחזירה תמונה ממוזערת בפורמט JPEG של סצנה ב-Street View. מאפשר לספק כותרת, גובה צליל, מידות ושדה ראייה. המידות המינימליות הן 16x16 פיקסלים. המידות המקסימליות הן 250x600 פיקסלים.
https://tile.googleapis.com/v1/streetview/metadata	מספק מידע מפורט על תמונת הפנורמה שצוינה. הפרטים כוללים את הכתובת הרלוונטית וקישורים לפנורמות סמוכות.

חיפוש תמונות פנורמיות ב-Street View

אפשר למצוא את מזהה הפנורמה של מיקום גיאוגרפי אחד או יותר על ידי העברת הקואורדינטות (lat, lng) לשיטה panoIds. גוף הבקשה הוא אובייקט JSON שמכיל מערך locations, ובאופן אופציונלי גם את radius, כפי שמוצג בדוגמה הבאה של קוד JSON.

curl -X POST -d '{
  "locations": [
    {"lat": -33.883837, "lng": 151.209307},
    {"lat": -33.883700, "lng": 151.210307},
    {"lat": 0, "lng": 0}
  ],
  "radius": 50
}' \
-H 'Content-Type: application/json' \
"https://tile.googleapis.com/v1/streetview/panoIds?session=YOUR_SESSION_TOKEN&key=YOUR_API_KEY"

locations

המערך locations חייב להכיל לפחות קבוצה אחת של ערכי קואורדינטות, אבל אפשר לכלול יותר, עד 100 לכל היותר.

radius

הערך radius (נמדד במטרים) מגדיר את רדיוס המעגל סביב המיקום הנתון, שבו יש לחפש תמונות פנורמה. ערך ברירת המחדל הוא 50 מטרים.

תשובה של PanoId

ה-API של אריחי המפה מנסה למצוא את התמונה הפנורמית הקרובה ביותר לכל מיקום, ולאחר מכן הוא מחזיר את המזהים הפנורמיים שלהם. בקשה מוצלחת של panoIds מחזירה אובייקט JSON שמכיל מערך panoIds. המערך מכיל רשימה של מזהי פנורמה, לפי הסדר שבו ביקשתם אותם. אם ה-API של אריחי המפה לא יכול למצוא פנורמות עבור המיקומים שביקשתם, תוחזר מחרוזת ריקה במיקום הזה במערך. לדוגמה, ראו את קוד ה-JSON הבא.

{
  "panoIds": [
    "ACfH-n2HcBvRry_3oc9grw",
    "f5DJZatBAAAXHlooS2wKbw",
    ""
  ]
}

אפשר להשתמש בpanoIds כדי:

• בקשת מטא-נתונים של Street View
• שליחת בקשה לתמונות ממוזערות של Street View
• שליחת בקשה לאריחים ב-Street View

הערה: מזהי פנורמה הם זמניים. כלומר, הם לא עמידים לאורך זמן. ככלל, לא מסתמכים על כך שמזהי פנורמה יהיו תקפים למשך יותר מסשן של משתמש יחיד.

מטא-נתונים של Street View

בקשות למטא-נתונים של Street View מאחזרות מידע על תמונות פנורמה. בקשת מטא-נתונים של Street View היא בקשת HTTPS GET. ניתן לאחזר מידע על תמונות פנורמה באחת משתי דרכים:

• אם מעבירים את הערך pano_id, ה-API של אריחי המפה מחזיר את המטא-נתונים של אותה פנורמה.

• אבל אם מעבירים lat ו-lng, ה-API של אריחי המפה מחזיר את המטא-נתונים של התמונה הפנורמית הקרובה ביותר ברדיוס החיפוש הנתון.

העברה של קבוצת קואורדינטות ורדיוס

curl "https://tile.googleapis.com/v1/streetview/metadata?session=YOUR_SESSION_TOKEN&key=YOUR_API_KEY&lat=lat&lng=lng&radius=meters"

מכיוון שמזהי פנורמה הם זמניים, מומלץ להעביר קבוצת קואורדינטות וערך radius בבקשת המטא-נתונים הראשונית של Street View. לדוגמה, אפשר לעיין בקטע הקוד הבא.

curl "https://tile.googleapis.com/v1/streetview/metadata?session=YOUR_SESSION_TOKEN&key=YOUR_API_KEY&lat=47.62066&lng=-122.34923&radius=50"

העברה של צילום פנורמי של תמונת Street View

curl "https://tile.googleapis.com/v1/streetview/metadata?session=YOUR_SESSION_TOKEN&key=YOUR_API_KEY&panoId=panoId"

תשובה למטא-נתונים

קוד ה-JSON הבא הוא דוגמה לתגובה אופיינית של מטא-נתונים.

{
 "panoId": "rZ9KeTyhA11i0VppYNzsSg",
 "lat": 37.420864219339165,
 "lng": -122.08446528377291,
 "imageHeight": 6656,
 "imageWidth": 13312,
 "tileHeight": 512,
 "tileWidth": 512,
 "heading": 94.35,
 "tilt": 88.39652,
 "roll": 1.7181772,
 "imageryType": "outdoor",
 "date": "2023-01",
 "copyright": "© 2023 Google",
 "reportProblemLink": "https://cbks0.googleapis.com/cbk?output=report&panoid=rZ9KeTyhA11i0VppYNzsSg&cb_client=api&cbp=1,0,,0,0&hl=en-US&gl=us",
 "addressComponents": [
  {
   "longName": "United States",
   "shortName": "United States",
   "types": [
    "country"
   ]
  },
  {
   "longName": "Mountain View, California",
   "shortName": "Mountain View, California",
   "types": [
    "locality"
   ]
  },
  {
   "longName": "Charleston Rd",
   "shortName": "Charleston Rd",
   "types": [
    "route"
   ]
  },
  {
   "longName": "1635",
   "shortName": "1635",
   "types": [
    "street_number"
   ]
  }
 ],
 "links": [
  {
   "panoId": "Yw4pqzA4FEq1qs-BwZSvSQ",
   "heading": 274.47998046875,
   "text": "Charleston Rd"
  },
  {
   "panoId": "1cODYwFRw1aZ45IignDIMw",
   "heading": 94.47999572753906,
   "text": "Charleston Rd"
  }
 ]
}

הרשימה הבאה מכילה הגדרות של השדות בגוף התשובה.

panoId

המזהה הייחודי של הפנורמה הזו. אין להסתמך על כך שמזהי פנורמה יהיו תקפים למשך יותר מסשן יחיד של משתמש.

lat, lng

הקואורדינטות (קווי אורך ורוחב) של הפנורמה. הערכים האלה יכולים להיות שונים מהקואורדינטות שהעברתם בבקשה, כי המיקום מוצמד לפנורמה הקרובה ביותר.

imageHeight, imageWidth

המידות של התמונה הפנורמית המחוברת.

tileHeight, tileWidth

המידות של משבצת פנורמה אחת.

heading

כיוון המצפן, במעלות, בכיוון צפון. הכותרות מוחזרות בטווח [0,360], כאשר 0 מייצג את הצפון.

tilt

הטיה של התמונה הפנורמית, שנמדדת במעלות מהקוטב הדרומי של הפנורמה עד האופק. הערכים המוחזרים נמצאים בטווח של [0, 180]. ערך של 90 מעלות מציין שהאופק כבר מיושר בקו המשווה של הפנורמה.

roll

הסיבוב בכיוון השעון מסביב לקו הראייה שהופעל על הפנורמה כדי ליישר את האופק. הערכים המוחזרים נמצאים בטווח [0, 360].

imageryType

מציין את סוג התמונה. הערכים החוקיים הם indoor ו-outdoor.

date

התאריך שבו התמונה צולמה. לא לכל התמונות יש נתוני תאריך. אבל כשהשדה הזה זמין, הוא מכיל שילוב של השנה (YYYY) וחודש (MM). לדוגמה: 2023-05 או 2024.

copyright

הטקסט של זכויות היוצרים שצריך להציג כייחוס יחד עם התמונה ב-Street View.

reportProblemLink

היפר-קישור שבאמצעותו המשתמשים יכולים לדווח על בעיות במשבצת של Street View. עליכם להציג את ההיפר-קישור בפינה השמאלית התחתונה של התמונה, והוא צריך לכלול טקסט קישור עם הכיתוב "Report a issue with this image" (דיווח על בעיה בתמונה הזו).

addressComponent

קוד גיאוגרפי מובנה שמכיל פרטים על הכתובת של התמונה הפנורמית. למידע נוסף, קראו את המאמר בקשות ותגובות לקידוד גיאוגרפי במסמכי התיעוד בנושא Geocoding API.

links

רשימה של מזהי פנורמה שכוללים קישור זה. מכילה גם את הכותרת שבה נמצא הקישור. לדוגמה, אם הכותרת היא 180°, אז הפנורמה המקושרת נמצאת מדרום לפנורמה הנוכחית. שים לב שבגלל האופי החולף של מזהי פנורמה, אין להסתמך עליהם יותר מאשר סשן אחד של משתמש.

תמונות ממוזערות של Street View

אפשר לבקש תמונות Street View בפורמט thumbnail. תמונות ממוזערות הן תמונות ללא משבצות עם גודל, כותרת, גובה ושדה ראייה שהוגדרו על ידי המשתמש. לתמונות ממוזערות יש רזולוציה נמוכה יותר מאשר משבצות, והן קטנות יותר בגודל הקובץ. כדי לשלוח בקשה לתמונה ממוזערת, שולחים בקשת GET לנקודת הקצה thumbnail, כפי שמוצג באב הטיפוס הבא של הקוד.

הערה: ערכי השדות שתחומים בסוגריים מרובעים בדוגמה הזו מציגים טווחים. לדוגמה, height יכול לנוע בין 16 ל-250 פיקסלים.

curl "https://tile.googleapis.com/v1/streetview/thumbnail?session=YOUR_SESSION_TOKEN&key=YOUR_API_KEY&panoId=panoId&height=FROM_16_TO_250&width=FROM_16_TO_600&pitch=FROM-90_TO_90&yaw=FROM-360_TO_360&fov=FROM_30_TO_120"

שימו לב לדוגמת הקוד הבאה, שמורידה תמונה ממוזערת של תמונות Street View שמצולמות בוויסטלר, קנדה.

curl "https://tile.googleapis.com/v1/streetview/thumbnail?session=YOUR_SESSION_TOKEN&key=YOUR_API_KEY&panoId=Zzl28rqGJgaL2IdkUleP8A&height=200&width=200&pitch=0&yaw=250&fov=80" --output /tmp/example_thumbnail.png

פרמטרים נדרשים

panoId

המזהה הייחודי של התמונה הממוזערת הרצויה. אפשר לקבל ערכים של מזהה פנורמה מנקודת הקצה panoIds או מנקודת הקצה metadata, ושתיהן מקבלות קואורדינטות גיאוגרפיות ומחזירות את ערך panoId המתאים.

session

אסימון סשן חוקי.

key

מפתח ה-API.

פרמטרים אופציונליים

height

ההגדרה קובעת את גובה התמונה הממוזערת בפיקסלים, בין 16 פיקסלים ל-250 פיקסלים. אם לא תציינו גובה, ברירת המחדל של הגובה היא לערך המקסימלי המותר של 250 פיקסלים. אם מציינים ערך מחוץ לטווח, התמונה הממוזערת תתפס לערך החוקי הקרוב ביותר.

width

ההגדרה קובעת את רוחב התמונה הממוזערת בפיקסלים, בין 16 פיקסלים ל-600 פיקסלים. אם לא תציינו רוחב, ברירת המחדל של הרוחב היא לערך המקסימלי המותר של 600 פיקסלים. אם מציינים ערך מחוץ לטווח, התמונה הממוזערת תתפס לערך החוקי הקרוב ביותר.

pitch

ההגדרה קובעת את זווית המצלמה לאורך הציר האנכי. הערכים החוקיים נמצאים בטווח -90 עד 90 (כולל). ערך ברירת המחדל הוא 0.

yaw

ההגדרה קובעת את כיוון המצלמה לאורך הציר האופקי. הערכים החוקיים נמצאים בטווח -360 עד 360 (כולל). ערך ברירת המחדל s 0.

fov

ההגדרה קובעת את שדה הראייה האופקי, שמבוטא במעלות, עם ערך מקסימלי של 120. כשמדובר באזור תצוגה בגודל קבוע, כמו בתמונה של Street View בגודל מוגדר, שדה הראייה מייצג את מרחק התצוגה, כאשר ערכים קטנים יותר מציינים רמה גבוהה יותר של מרחק מתצוגה. ערך ברירת המחדל הוא 90.

משבצות של תמונות Street View

ברגע שיש לכם panoId, תוכלו לבקש משבצת של תמונה ב-Street View. בקשות של משבצות הן בקשות מסוג HTTPS GET. עיינו בדוגמה הבאה.

curl "https://tile.googleapis.com/v1/streetview/tiles/z/x/y?session=YOUR_SESSION_TOKEN&key=YOUR_API_KEY&panoId=panoId"

בדוגמה הזו לקוד, z היא רמת המרחק מהתצוגה, ו-x ו-y הן הקואורדינטות של המשבצות של משבצת Street View הרצויה. רמות הזום בפנורמות של Street View חייבות להיות בטווח של [0,5], כאשר 0 מייצג את שדה הראייה הרחב ביותר.

מרחק מתצוגה	שדה ראייה משוער
0	360°
1	180°
2	90°
3	19°
4	22.5°
5	11.25°

הערה: התמונות ב-Street View מגיעות משני מקורות: Google (תמונות שאינן בשליטת המפתח) והציבורית (תוכן שנוצר על ידי המשתמש או תוכן ציבורי שנוצר על ידי משתמשים). שים לב שאין דרך להשתמש רק במקור אחד של תמונות Street View על פני המקור השני. מידע נוסף על מדיניות הפרטיות בנושא תמונות Street View.

תגובות לאריחים ב-Street View

בקשה מוצלחת של אריח Street View מחזירה תמונה בפורמט ובגודל שציינתם בתשובה createSession.

ברמת הזום אפס, הגודל של כל הפנורמה משתנה למשבצת בגודל tileWidth על tileHeight. מכיוון שתמונות פנורמיות גדולות יותר בממד ה-x, האריח יכיל שטח ריק במאפיין ה-y:

ברמת זום 5, נעשה שימוש בפנורמה בגודל מלא ומחולקת לאריחים.

טיפ: אפשר לחשב את הערכים המקסימליים x ו-y על ידי חלוקת imageHeight ו-imageWidth במספר tileHeight ו-tileWidth.

מידע על זכויות יוצרים

עליכם להציג פרטי זכויות יוצרים בכל תמונת פנורמה של Street View. המחרוזת להצגה עשויה להשתנות בין תמונות פנורמה. על מנת לקבל את המידע על זכויות היוצרים, עליכם לבקש מטא-נתונים של Street View, ולאחר מכן תוכלו לעיין בשדה copyright של התשובה. מידע נוסף זמין במאמר שיוך נתונים (Attribution).