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

העברת ה-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:

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

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

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