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