אריחי Street View

מפתחים באזור הכלכלי האירופי (EEA)

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

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

  • משבצות ב-Google Street View
  • מטא-נתונים של 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 מספק מידע מפורט על תמונת הפנורמה שצוינה. הפרטים כוללים את הכתובת הרלוונטית וקישורים לתמונות פנורמיות סמוכות.

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

ה-API של Map Tiles מנסה למצוא את התמונה הפנורמית הכי קרובה לכל מיקום, ואז מחזיר את מזהי התמונות הפנורמיות. בקשת panoIds מוצלחת מחזירה אובייקט JSON שמכיל מערך panoIds. המערך מכיל רשימה של מזהי תמונות פנורמיות, לפי הסדר שבו ביקשתם אותם. אם Map Tiles API לא מוצא תמונות פנורמיות למיקומים שביקשתם, מחרוזת ריקה מוחזרת במיקום הזה במערך. לדוגמה, אפשר לעיין בקוד ה-JSON הבא.

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

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

מטא-נתונים של 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

תמונה ממוזערת של Whistler, קנדה, ב-Street View

פרמטרים נדרשים

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

מרחק מתצוגה שדה ראייה משוער
0 360°
1 180°
2 90°
3 45°
4 ‫22.5°
5 ‫11.25°

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

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

התוצאה של בקשה מוצלחת לחיבור בין המשבצות

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

רמת זום אפס

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

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