אריחי Street View

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

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

משבצות ב-Street View דומות למשבצות דו-ממדיות, אבל הן מכילות תמונות פנורמיות שצולמו ברמת הרחוב. באמצעות Street View תוכלו לסייר באתרים מפורסמים בעולם, לראות פלאי טבע ולהיכנס למקומות כמו מוזיאונים, אצטדיונים, מסעדות או עסקים קטנים. נקודת הקצה (endpoint) הזו של ה-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) לשיטה 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 היא בקשת 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
הטקסט בנושא זכויות יוצרים שחובה להציג כהפניה למקור לצד תמונת Street View.
reportProblemLink
היפר-קישור שהמשתמשים יכולים להשתמש בו כדי לדווח על בעיות במשבצת הזו של תמונת רחוב. חובה להציג את ההיפר-קישור הזה בפינה השמאלית התחתונה של התמונה, והוא צריך לכלול טקסט של קישור כמו "דיווח על בעיה בתמונה הזו".
addressComponent
Geocode מובנה שמכיל פרטים על כתובת הפנורמה. מידע נוסף זמין במאמר בקשות ותגובות של 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

תמונה ממוזערת של 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. בקשות Tile הן בקשות 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.

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

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

רמת זום אפס

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

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