本頁面由 Cloud Translation API 翻譯而成。

街景服務動態磚

歐洲經濟區 (EEA) 開發人員

街景服務圖塊範例

街景服務圖塊與2D 圖塊類似，但包含在街道層級拍攝的全景圖像。街景服務可帶你走訪全球地標、欣賞自然奇觀，還能一窺眾多博物館、運動場、餐廳或小型商家的內部實景。這個 API 端點可讓您存取：

Google 地圖街景服務圖塊
街景服務中繼資料
街景服務縮圖

你可以將街道層級的圖片圖塊縫合在一起，製作出真實的全景效果。您最多可以查詢一組地點 (例如路線) 的 100 個全景 ID，並取得相機位置的深入中繼資料。

你必須使用檢視器將街景服務圖塊縫合在一起。例如，街景服務自訂全景檢視器。

取得 API 金鑰後，即可按照下列步驟存取街景服務圖像。

取得工作階段權杖。請務必將 mapType 的值設為 streetview。
使用工作階段權杖取得一或多個地理位置的全景 ID (panoId)。
使用 panoId 搜尋回應中的全景 ID，取得下列資訊：
1. 街景服務中繼資料。您也可以傳遞一組座標和半徑，取得街景檢視中繼資料。
2. 街景服務縮圖。
3. 街景服務圖塊。

街景服務方法

您可以呼叫下列四種方法之一，存取街景服務圖像和中繼資料。

方法	說明
`https://tile.googleapis.com/v1/streetview/tiles`	傳回個別街景服務圖塊。您可以擷取六個縮放等級的街景服務圖塊：從 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`	提供指定全景的詳細資訊。詳細資料包括相關地址，以及鄰近全景的連結。

搜尋街景服務 panoId

如要取得一或多個地理位置的全景 ID，請將座標 (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 會嘗試找出最接近每個位置的全景，然後傳回全景 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 是暫時性的，因此建議您在初始的 Street View 中繼資料要求中，傳遞一組座標和 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。您不應依賴 Panorama ID 在單一使用者工作階段以外的時間保持有效。
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: 您必須顯示的著作權文字，做為街景圖片的註記。
reportProblemLink: 超連結：使用者可透過這個連結回報此街景服務圖塊的問題。您必須在圖片右下角顯示這個超連結，且連結文字必須類似「回報這張圖片的問題」
addressComponent: 結構化地理編碼，內含全景地址的詳細資料。詳情請參閱 Geocoding API 說明文件中的「Geocoding 請求和回應」一節。
links: 連結至這個全景的 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 像素，這是允許的最大值。如果指定的值超出範圍，縮圖會貼齊最接近的有效值。
width: 以像素為單位指定縮圖寬度，範圍為 16 像素到 600 像素。如未指定寬度，寬度預設為 600 像素，這是允許的最大值。如果指定的值超出範圍，縮圖會貼齊最接近的有效值。
pitch: 指定相機沿垂直軸的角度。有效值介於 -90 至 90 之間 (包括 -90 和 90)。預設值為 0。
yaw: 指定攝影機沿水平軸的方向。有效值介於 -360 至 360 之間 (包括 -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 回應中指定的格式和大小圖片。

成功 Tile 要求的結果

在縮放等級為零時，整個全景會調整為 tileWidth x tileHeight 的圖塊。由於全景圖片在 x 維度較大，圖塊在 y 維度會包含空白空間：

縮放等級為零

縮放等級為 5 時，系統會使用完整大小的全景，並將其分割為圖塊。

著作權資訊

您必須在每個街景服務全景中顯示著作權資訊。顯示的字串會因全景而異。如要取得著作權資訊，請先要求 Street View 中繼資料，然後參閱回應的 copyright 欄位。詳情請參閱資料歸因。