街景服務動態磚

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

街景服務圖塊範例

街景服務圖塊與 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 傳回個別街景服務圖塊。您可以擷取六種縮放等級的街景服務圖塊：從 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 提供指定全景的詳細資訊。詳細資料包括相關地址，以及鄰近全景的連結。

您可以將一或多個地理位置的座標 (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 的用途包括：

街景服務中繼資料

街景服務中繼資料要求會擷取全景的相關資訊。街景服務中繼資料要求是 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。您不應仰賴 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 說明文件中的「地理編碼要求和回應」一節。
links
連結至這個全景的 ID 清單。此外，也包含找到連結的標題。舉例來說，如果航向為 180°，則連結的全景位於目前全景的正南方。請注意，全景 ID 具有暫時性，因此不應在單一使用者工作階段以外使用。

街景服務縮圖

您可以要求 thumbnail 格式的街景服務圖像。縮圖是非並排圖片，使用者可自訂大小、航向、俯仰角和視野。縮圖圖片的解析度低於圖塊，檔案大小也較小。如要提出縮圖要求，請向 thumbnail 端點傳送 GET 要求，如以下程式碼原型所示。

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 維度會包含空白空間：

縮放等級為零

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

每個街景服務全景都必須顯示著作權資訊。要顯示的字串可能因全景而異。如要取得著作權資訊，請先要求 街景服務中繼資料，然後參閱回應的 copyright 欄位。詳情請參閱「資料作者資訊」。