אריחי 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

המזהה הייחודי של התמונה הפנורמית. אל תסתמכו על כך שמזהי 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

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

reportProblemLink

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

addressComponent

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

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:

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

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

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