街景服務圖塊與 2D 圖塊類似，差別在於其中包含在街道層級拍攝的全景圖像。透過街景服務，您可以探索全球地標、觀看自然奇觀，並一窺博物館、運動場、餐廳或小型商家的內部實景。
這個 API 端點可讓您存取：
- Google 地圖街景服務圖塊
- 街景服務中繼資料
- 街景服務縮圖
您可以將從街道層級拍攝的圖塊拼接在一起，創造真實的全景效果。您還能針對一組地點 (例如路線) 查詢最多 100 個全景 ID，並取得有關相機位置的深入中繼資料。
檢視者必須將街景服務圖塊拼接在一起。例如街景服務自訂全景檢視器。
取得 API 金鑰後，請執行下列步驟，存取街景服務圖像。
取得工作階段符記。請務必將
mapType的值設為streetview。使用工作階段符記，取得一或多個地理位置的全景 ID (panoId)。
使用 panoId 搜尋回應中的全景 ID 即可取得：
街景服務方法
如要存取街景服務圖像和中繼資料，請呼叫下列其中一種方法。
| 方法 | 說明 |
|---|---|
https://tile.googleapis.com/v1/streetview/tiles |
傳回個別的街景服務圖塊。你可以擷取六個縮放等級 (最多 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 清單，並按照您要求 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 的全景 ID 清單。同時包含連結所在標題。舉例來說，如果方向是 180°，連結的全景就是目前全景的南方。請注意，全景 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 像素。如果指定的值超出範圍，則縮圖會「snaps」最接近有效值。
width- 指定縮圖的寬度 (以像素為單位)，範圍介於 16 像素到 600 像素之間。如未指定寬度，寬度會預設為允許的最大值 600 像素。如果指定的值超出範圍，則縮圖會「snaps」最接近有效值。
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 | 7\u00B0 |
| 4 | 37° |
| 5 | 11.25° |
街景服務圖塊回應
成功的街景服務圖塊要求會傳回您在 createSession 回應中指定的格式和大小圖片。
縮放等級為 0 時，系統會將整個全景大小調整為 tileWidth 尺寸的 tileHeight 圖塊。由於全景的 x 尺寸較大，因此圖塊的 y 維度中會含有空白空間：
縮放等級為五時，會使用完整大小的全景圖，並分割成多個圖塊。
xy著作權資訊
您必須在每張街景服務全景展示版權資訊。要在每張全景間顯示的字串都不同。如要取得版權資訊，您必須要求街景服務中繼資料，然後參照回應的 copyright 欄位。詳情請參閱「資料歸因」。