אריחי Street View

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

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

   3. משבצות ב-Street View.

שיטות של Street View

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

חיפוש של מזהי תמונות פנורמיות ב-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

ה-Map Tiles 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 מחזיר את המטא-נתונים של התמונה הפנורמית הקרובה ביותר ברדיוס החיפוש שצוין.

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

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"

העברת ה-panoId של תמונת 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

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

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

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

reportProblemLink

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

addressComponent

Geocode מובנה שמכיל פרטים על הכתובת של התמונה הפנורמית. מידע נוסף זמין בקטע בקשות ותשובות של גיאוקוד במסמכי העזרה של 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 (כולל). ערך ברירת המחדל הוא 0.

fov

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

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

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

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 מייצג את שדה הראייה הרחב ביותר.

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

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

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

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

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

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