街景服務動態磚

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

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

您可以將街道層拍攝的圖塊拼接在一起，創造真實的全景效果。您可以針對一組位置 (例如路線) 查詢最多 100 個全景 ID，並取得有關相機位置的更深入中繼資料。

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

取得 API 金鑰後，您可以執行下列步驟存取街景服務圖像。

  1. 取得工作階段符記。請務必將 mapType 的值設為 streetview。

  2. 使用工作階段權杖，取得一或多個地理位置的全景 ID (panoId)。

  3. 使用 panoId 搜尋回應中的全景 ID，取得以下資訊：

    1. 街景服務中繼資料：您也可以傳遞一組座標和半徑，取得街景服務中繼資料。

    2. 街景服務縮圖。

    3. 街景服務圖塊。

街景服務方法

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

方法 說明
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 縮圖。可讓您提供標頭、傾斜度、尺寸和視野。最小尺寸為 16 x 16 像素。尺寸上限為 250x600 像素。
https://tile.googleapis.com/v1/streetview/metadata 提供指定全景相片的詳細資訊。詳細資料包括相關地址，以及相鄰全景圖的連結。

您可以將座標 (lat、lng) 傳遞至 panoIds 方法，找出一個或多個地理位置的環景相片 ID。要求主體是 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 執行以下操作：

街景服務中繼資料

街景服務中繼資料要求會擷取全景的相關資訊。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"

由於全景 ID 是暫時性的，建議您在初始的 Google 街景中繼資料要求中傳遞一組座標和 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
結構化 Geocode，其中包含全景圖的地址詳細資料。詳情請參閱 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 回應中指定的格式和大小的圖片。

成功的資訊方塊要求結果

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

縮放層級為零

在縮放等級 5 時，系統會使用全尺寸全景圖並分割成圖塊。

您必須在每張街景服務全景中顯示版權資訊。顯示的字串可能因全景相片而異。如要取得版權資訊，您必須要求街景服務中繼資料，然後參考回應的 copyright 欄位。詳情請參閱「資料歸因」。