街景服務動態磚

街景服務範例街景服務圖塊與 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 圖片。可讓您提供標頭、傾斜度、尺寸和視野。尺寸下限為 16x16 像素。尺寸上限為 250x600 像素。
https://tile.googleapis.com/v1/streetview/metadata 提供指定全景相片的詳細資訊。詳細資訊包括相關地址,以及相鄰的全景連結。

您可以將座標 (latlng) 傳遞至 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 就會傳回該全景圖的中繼資料。

  • 不過,如果您傳遞 latlng,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 的有效期限超過單一使用者工作階段。
latlng
全景圖的座標 (經度和緯度)。這些值可能與您在要求中傳遞的座標不同,因為位置會對齊最近的全景圖。
imageHeightimageWidth
已拼接的全景圖像尺寸。
tileHeighttileWidth
單一全景圖塊的尺寸。
heading
指南針方位,以度為單位,從正北順時針測量。系統會在 [0,360] 範圍內傳回標頭,其中 0 代表正北。
tilt
全景圖的傾斜角度,以度為單位,從全景圖的南極到地平線測量。傳回的值在 [0, 180] 範圍內。值為 90 度表示地平線已對齊全景圖的赤道。
roll
沿著視線方向順時針旋轉,以便將全景圖的水平線調整至水平。傳回的值介於 [0, 360] 之間。
imageryType
指示圖片類型。有效值為 indooroutdoor
date
圖片拍攝日期。並非所有圖片都有日期資料。但如果可用,這個欄位會包含年份 (YYYY) 和月份 (MM) 的組合。例如:2023-05 或 2024。
copyright
您必須在街景圖片中顯示的版權文字。
reportProblemLink
這個超連結可讓使用者回報這個街景服務圖塊的問題。您必須在圖片的右下角顯示這項超連結,且連結文字必須包含類似「回報此圖片的問題」的文字。
addressComponent
結構化 Geocode,其中包含全景圖的詳細地址。詳情請參閱 Geocoding API 說明文件中的「地理編碼要求和回應」一文。
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
指定相機沿垂直軸的角度。有效值介於 -9090 之間 (含頭尾)。預設值為 0。
yaw
指定相機沿水平軸的方向。有效值介於 -360360 之間 (含首尾)。預設值為 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 是縮放等級,xy 則是您所需街景服務圖塊的圖塊座標。街景服務全景圖的縮放等級必須介於 [0,5] 之間,其中 0 代表最寬的視野範圍。

縮放級別 大約視野
0 360°
1 180°
2 90°
3 45°
4 37°
5 11.25°

街景服務圖塊回應

成功的街景服務圖塊要求會傳回 createSession 回應中指定的格式和大小圖片。

成功的資訊方塊要求結果

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

縮放層級為零

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

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