אריחי 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, אפשר להפעיל אחת מארבע השיטות הבאות.

חיפוש מזהי פנורמה ב-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 היא בקשת GET של HTTPS. יש שתי דרכים לאחזר מידע על תמונות פנורמיות:

• אם מעבירים 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

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

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

addressComponent

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

תגובות של משבצות ב-Street View

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

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

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

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

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