כרטיסי Street View דומים למשבצות דו-ממדיות, אבל הם מכילים תמונות פנורמיות שצולמו ברמת הרחוב. באמצעות Street View אפשר לסייר באתרים מפורסמים בעולם, לראות פלאי טבע ולהיכנס למקומות כמו מוזיאונים, אצטדיונים, מסעדות או עסקים קטנים. נקודת הקצה ב-API מאפשרת גישה אל:
- משבצות Street View במפות Google
- מטא-נתונים של Street View
- תמונות ממוזערות של Street View
אפשר לחבר יחד אריחי תמונות שצולמו מרמת הרחוב כדי ליצור אפקט פנורמי אמיתי. אפשר גם לשלוח שאילתות על עד 100 מזהים של תמונות פנורמה לקבוצת מיקומים (כמו מסלול), ולקבל מטא-נתונים מעמיקים יותר לגבי מיקום המצלמה.
הצופה נדרש לחבר משבצות של Street View יחד. לדוגמה, מציג תמונות פנורמה בהתאמה אישית ב-Street View.
אחרי שיש לכם מפתח API, אפשר לגשת לתמונות Street View על ידי ביצוע השלבים הבאים.
מקבלים אסימון סשן. חשוב להגדיר את הערך של
mapType
ל-streetview
.משתמשים באסימון הסשן כדי לקבל את מזהה הפנורמה (panoId) של מיקום גיאוגרפי אחד או יותר.
משתמשים במזהי הפנורמה מתגובת החיפוש של PanoId כדי לקבל:
מטא-נתונים של Street View. תוכלו גם לקבל מטא-נתונים של 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 |
מספק מידע מפורט על הפנורמה שצוינה. הפרטים כוללים את הכתובת הקשורה וקישורים לתמונות פנורמה סמוכות. |
חיפוש של תמונות פנורמיות ב-Street View
כדי למצוא את המזהה הפנורמה של מיקום גיאוגרפי אחד או יותר, אפשר להעביר את הקואורדינטות שלהם (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
ה-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 היא בקשת 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"
העברת הפנורמה של תמונת 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
- הקואורדינטות (קווי אורך ורוחב) של נוף הפנורמה. הערכים האלה יכולים להיות שונים מהקואורדינטות שהעברת בבקשה, כי המיקום sמצולם לפנורמה הקרובה ביותר.
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
פרמטרים נדרשים
panoId
- המזהה הייחודי של התמונה הממוזערת הרצויה. אפשר לקבל את הערכים של המזהים הפנורמיים מנקודת הקצה
panoIds
או מנקודת הקצהmetadata
, ובשניהם מקבלים קואורדינטות גיאוגרפיות ומחזירים את ה-panoId
המתאים. session
- אסימון סשן חוקי.
key
- מפתח ה-API.
פרמטרים אופציונליים
height
- ההגדרה קובעת את גובה התמונה הממוזערת בפיקסלים, בין 16 פיקסלים ל-250 פיקסלים. אם לא מציינים גובה, ברירת המחדל של הגובה היא 250 פיקסלים. אם מציינים ערך שחורג מהטווח, התמונה הממוזערת תצמיד לערך החוקי הקרוב ביותר.
width
- ההגדרה קובעת את רוחב התמונה הממוזערת בפיקסלים, בין 16 פיקסלים ל-600 פיקסלים. אם לא מציינים רוחב, ברירת המחדל של הרוחב תהיה 600 פיקסלים. אם מציינים ערך שחורג מהטווח, התמונה הממוזערת תצמיד לערך החוקי הקרוב ביותר.
pitch
- ההגדרה קובעת את זווית המצלמה לאורך הציר האנכי. הערכים החוקיים נמצאים בטווח
-90
עד90
(כולל). ערך ברירת המחדל הוא 0. yaw
- ההגדרה קובעת את כיוון המצלמה לאורך הציר האופקי. הערכים החוקיים נמצאים בטווח
-360
עד360
(כולל). ערך ברירת המחדל s 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 | 19° |
4 | 22.5° |
5 | 11.25° |
תגובות במשבצות Street View
כשבקשת המשבצת של Street View מצליחה, מוחזרת תמונה בפורמט ובגודל שציינתם בתשובה createSession
.
ברמת זום אפס, הגודל של כל התמונה הפנורמית משתנה למשבצת במידות tileWidth
על ידי tileHeight
. מכיוון שתמונות פנורמה גדולות יותר במימד ה-x, האריח יכיל שטח ריק בממד ה-y:
ברמת זום 5, התמונה הפנורמית בגודל מלא מחולקת למשבצות.
מידע על זכויות יוצרים
יש להציג מידע על זכויות יוצרים בכל פנורמה של Street View. המחרוזת להצגה עשויה להשתנות בין תמונות פנורמיות. כדי לקבל את פרטי זכויות היוצרים, צריך לבקש מטא-נתונים של Street View, ולאחר מכן תוכלו
לעיין בשדה copyright
של התשובה. מידע נוסף מופיע במאמר שיוך של נתונים.