אריחי Street View

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

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

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

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

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

התוצאה של בקשה מוצלחת להצגת משבצת

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

רמת זום אפס

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

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