אריחי Street View

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

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

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

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

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

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

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

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

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

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

   3. כרטיסי מידע של Street View.

שיטות של 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) ל-method 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. המערך מכיל רשימה של מזהי פנורמה, לפי הסדר שבו ביקשתם אותם. אם Map Tiles API לא מצליח למצוא תמונות פנורמה של המיקומים שביקשת, תוחזר מחרוזת ריקה במיקום הזה במערך. לדוגמה, ראו את קוד ה-JSON הבא.

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

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

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

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

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

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

• אבל אם מעבירים את הערכים lat ו-lng, אז Map Tiles 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

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

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

addressComponent

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

links

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

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

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

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

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

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

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

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

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