街景服務圖塊與 2D 圖塊相似，但當中包含在街道層級拍攝的全景圖像。街景服務可帶你走訪全球地標、欣賞自然奇觀，還能一窺眾多博物館、運動場、餐廳或小型商家的內部實景。這個 API 端點可讓您存取：
- Google 地圖街景服務圖塊
- 街景服務中繼資料
- 街景服務縮圖
您可以拼接從街道層級拍攝的圖片圖塊，藉此建立真實全景效果。您也可以針對一組地點 (例如路線) 查詢最多 100 個全景 ID，並取得相機位置的相關詳盡中繼資料。
必須由檢視器將街景服務圖塊拼接在一起。舉例來說，街景服務自訂全景檢視器。
取得 API 金鑰後，您就可以執行下列步驟存取街景服務圖像。
取得工作階段符記。請務必將
mapType的值設為streetview。使用工作階段符記來取得一或多個地理位置的全景 ID (panoId)。
使用 panoId 搜尋回應中的全景 ID 取得：
街景服務方法
您可以呼叫下列四種方法，存取街景服務圖像和中繼資料。
| 方法 | 說明 |
|---|---|
https://tile.googleapis.com/v1/streetview/tiles |
傳回個別街景服務圖塊。您可以擷取 6 個縮放等級的「街景服務圖塊：最高 512 像素，最高 13,312 像素」。 |
https://tile.googleapis.com/v1/streetview/panoIds |
可讓您一次搜尋最多 100 個地點。傳回所有包含圖像的全景 ID。 |
https://tile.googleapis.com/v1/streetview/thumbnail |
傳回街景服務場景的 JPEG 縮圖。可讓您提供標題、提案、尺寸和視野。尺寸下限為 16x16 像素。尺寸上限為 250x600 像素。 |
https://tile.googleapis.com/v1/streetview/metadata |
提供特定全景的詳細資訊。詳細資料包括相關地址以及相鄰全景相片的連結。 |
街景服務 panoIds 搜尋
如要找出一或多個地理位置的全景 ID，請將這些地理位置的座標 (lat、lng) 傳遞至 panoIds 方法。要求主體是包含 locations 陣列和選用 radius 的 JSON 物件，如以下 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
locationslocations陣列必須包含至少一組座標值，但您可以加入更多座標值 (最多 100 組)。radiusradius值 (以公尺為單位) 定義特定位置周圍的圓形半徑，在此搜尋全景。預設值為 50 公尺。
PanoId 回應
Map Tiles API 會嘗試找出離每個地點最近的全景，然後傳回全景 ID。成功的 panoIds 要求會傳回包含 panoIds 陣列的 JSON 物件。陣列包含全景 ID 清單，且會按照您要求的順序排列。如果 Map Tiles API 找不到您要求的地點全景，系統會在陣列中的該位置傳回空白字串。如需範例，請參閱下列 JSON 程式碼。
{
"panoIds": [
"ACfH-n2HcBvRry_3oc9grw",
"f5DJZatBAAAXHlooS2wKbw",
""
]
}
您可以使用 panoIds 執行以下動作：
街景服務中繼資料
街景服務中繼資料要求會擷取全景相關資訊。街景服務中繼資料要求是一種 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"
由於全景 ID 是暫時性的，建議您在初始街景服務中繼資料要求中傳遞一組座標和 radius 值。如需範例，請參閱下列程式碼片段。
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
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- 這個全景的專屬 ID。請勿在單一使用者工作階段期間依賴全景 ID 的有效期間。
lat、lng- 全景的座標 (經緯度)。這些值可以不同於您在要求中傳遞的座標，因為位置 snaps 是距離最近的全景。
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- 您必須連同街景服務圖片一併顯示的版權文字。
reportProblemLink- 使用者可運用超連結，回報這個街景服務圖塊的問題。您必須在圖片右下角顯示這類超連結，且必須包含「回報這張圖片的問題」等連結文字。
addressComponent- 結構化地理編碼，包含全景地址的詳細資料。詳情請參閱 Geocoding API 說明文件中的地理編碼要求和回應。
links- 連結至這張圖片的全景 ID 清單。也包含連結所在的標題。舉例來說，如果標題為 180°，則連結的全景會是目前全景的南方。請注意，由於全景 ID 屬於暫時性的，因此除了單一使用者工作階段，請不要使用這些 ID。
街景服務縮圖
你可以索取 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"
請參考以下程式碼範例，這個程式碼下載了在加拿大威斯勒市拍攝的街景服務圖像縮圖。
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- 所需縮圖的專屬 ID。您可以從
panoIds端點或metadata端點取得全景 ID 值，兩者皆接受地理座標，然後傳回適當的panoId。 session- 有效的工作階段符記。
key- 您的 API 金鑰。
自選參數
height- 指定縮圖的高度 (以像素為單位)，範圍介於 16 像素到 250 像素之間。如果未指定高度，高度會預設為允許的最大值 250 像素。如果您指定的值超出範圍，則縮圖會切記到最接近的有效值。
width- 指定縮圖的寬度 (以像素為單位)，範圍介於 16 像素到 600 像素之間。如果未指定寬度，則寬度會預設為 600 像素的允許值上限。如果您指定的值超出範圍，縮圖會剪輯到最接近的有效值。
pitch- 指定攝影機沿著垂直軸的角度。有效值介於
-90到90之間 (含首尾)。預設值為 0。 yaw- 指定攝影機在水平軸上的方向。有效值的範圍介於
-360到360之間 (含首尾)。預設值為 0。 fov- 指定水平視野 (以度為單位)，最大值為 120。處理固定大小的可視區域時，就像處理單一尺寸的街景服務圖片一樣，視野代表縮放，而較小的值可指定較高的縮放等級。預設值為 90。
街景服務圖像圖塊
取得 panoId 後，您就可以要求街景服務圖片圖塊。資訊方塊要求是 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 則是所需街景服務圖塊的圖塊座標。街景服務全景的縮放等級必須是 [0,5] 的範圍，其中 0 代表最寬的視野。
| 縮放級別 | 概略視野 |
|---|---|
| 0 | 360 度 |
| 1 | 180° |
| 2 | 90° |
| 3 | 45° |
| 4 | 22.5° |
| 5 | 11.25° |
街景服務圖塊回應
成功的街景服務圖塊要求會傳回您在 createSession 回應中指定的格式和大小圖片。
縮放等級為 0 時，系統會以 tileHeight 將整個全景調整為 tileWidth 尺寸的圖塊。全景圖在 x 維度中較大，因此 y 尺寸圖塊會包含空白空間：
縮放等級為 5 時，系統會使用原尺寸全景，然後分割成圖塊。
版權資訊
每張街景服務全景都必須顯示版權資訊。每張全景的顯示字串可能有所不同。如要取得版權資訊，您必須要求街景服務中繼資料，然後才能參照回應的 copyright 欄位。詳情請參閱「資料歸因」。