Ô chế độ xem phố

Nhà phát triển ở Khu vực kinh tế Châu Âu (EEA)

Ví dụ về ô Chế độ xem đường phố

Ô Chế độ xem phố tương tự như Ô 2D , ngoại trừ việc chúng chứa hình ảnh toàn cảnh được chụp ở cấp đường phố. Thông qua Chế độ xem đường phố, bạn có thể khám phá các địa danh trên thế giới, xem các kỳ quan thiên nhiên và tham quan các địa điểm như bảo tàng, sân vận động, nhà hàng hoặc doanh nghiệp nhỏ. Điểm cuối API này cho phép bạn truy cập vào:

Ô Chế độ xem phố trong Google Maps
Siêu dữ liệu của Chế độ xem đường phố
Hình thu nhỏ của Chế độ xem đường phố

Bạn có thể ghép các ô hình ảnh được chụp ở cấp đường phố để tạo hiệu ứng toàn cảnh như trong thực tế. Ngoài ra, bạn có thể truy vấn tối đa 100 mã ảnh toàn cảnh cho một tập hợp các vị trí (chẳng hạn như một tuyến đường) và nhận thêm siêu dữ liệu chi tiết về vị trí của camera.

Bạn cần có một trình xem để ghép các Ô Chế độ xem phố. Ví dụ: trình xem ảnh toàn cảnh tuỳ chỉnh của Chế độ xem đường phố.

Sau khi có khoá API, bạn có thể truy cập vào hình ảnh trong Chế độ xem đường phố bằng cách thực hiện các bước sau.

Nhận mã phiên. Hãy nhớ đặt giá trị của mapType thành streetview.
Sử dụng mã phiên để nhận giá trị nhận dạng ảnh toàn cảnh (panoId) của một hoặc nhiều vị trí địa lý.
Sử dụng giá trị nhận dạng ảnh toàn cảnh từ phản hồi tìm kiếm panoId để nhận:
1. Siêu dữ liệu của Chế độ xem đường phố. Bạn cũng có thể nhận siêu dữ liệu của Chế độ xem phố bằng cách truyền một tập hợp toạ độ và bán kính.
2. Hình thu nhỏ của Chế độ xem đường phố.
3. Ô Chế độ xem phố.

Phương thức của Chế độ xem đường phố

Bạn có thể truy cập vào hình ảnh trong Chế độ xem đường phố và siêu dữ liệu bằng cách gọi một trong 4 phương thức sau.

Phương thức	Mô tả
`https://tile.googleapis.com/v1/streetview/tiles`	Trả về các Ô Chế độ xem phố riêng lẻ. Bạn có thể truy xuất Ô Chế độ xem phố ở 6 cấp thu phóng: từ 512 pixel đến 13.312 pixel.
`https://tile.googleapis.com/v1/streetview/panoIds`	Cho phép bạn tìm kiếm hàng loạt tối đa 100 vị trí. Trả về mã ảnh toàn cảnh cho tất cả các vị trí có hình ảnh.
`https://tile.googleapis.com/v1/streetview/thumbnail`	Trả về hình ảnh JPEG thu nhỏ của một cảnh trong Chế độ xem đường phố. Cho phép bạn cung cấp tiêu đề, độ nghiêng, kích thước và trường nhìn. Kích thước tối thiểu là 16x16 pixel. Kích thước tối đa là 250x600 pixel.
`https://tile.googleapis.com/v1/streetview/metadata`	Cung cấp thông tin chi tiết về ảnh toàn cảnh được chỉ định. Thông tin chi tiết bao gồm địa chỉ liên quan và đường liên kết đến các ảnh toàn cảnh liền kề.

Tìm kiếm panoIds của Chế độ xem đường phố

Bạn có thể tìm thấy giá trị nhận dạng ảnh toàn cảnh của một hoặc nhiều vị trí địa lý bằng cách truyền toạ độ (lat, lng) của các vị trí đó đến phương thức panoIds. Nội dung yêu cầu là một đối tượng JSON chứa một mảng locations và tuỳ ý, một radius, như minh hoạ trong ví dụ về mã JSON sau.

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: Mảng locations phải chứa ít nhất một tập hợp các giá trị toạ độ, nhưng bạn có thể đưa thêm (tối đa 100).
radius: Giá trị radius (được đo bằng mét) xác định bán kính của vòng tròn xung quanh vị trí đã cho, trong đó tìm kiếm ảnh toàn cảnh. Giá trị mặc định là 50 mét.

Phản hồi PanoId

Map Tiles API cố gắng tìm ảnh toàn cảnh gần nhất với mỗi vị trí, sau đó trả về mã ảnh toàn cảnh của các vị trí đó. Yêu cầu panoIds thành công sẽ trả về một đối tượng JSON chứa một mảng panoIds. Mảng này chứa danh sách mã ảnh toàn cảnh theo thứ tự mà bạn đã yêu cầu. Nếu Map Tiles API không tìm thấy ảnh toàn cảnh nào cho các vị trí mà bạn đã yêu cầu, thì một chuỗi trống sẽ được trả về tại vị trí đó trong mảng. Để xem ví dụ, hãy xem mã JSON sau.

{
  "panoIds": [
    "ACfH-n2HcBvRry_3oc9grw",
    "f5DJZatBAAAXHlooS2wKbw",
    ""
  ]
}

Bạn có thể sử dụng panoIds để:

Yêu cầu siêu dữ liệu của Chế độ xem đường phố
Yêu cầu hình thu nhỏ của Chế độ xem đường phố
Yêu cầu Ô Chế độ xem phố

Siêu dữ liệu của Chế độ xem đường phố

Yêu cầu siêu dữ liệu của Chế độ xem đường phố truy xuất thông tin về ảnh toàn cảnh. Yêu cầu siêu dữ liệu của Chế độ xem phố là một yêu cầu GET HTTPS. Bạn có thể truy xuất thông tin về ảnh toàn cảnh theo một trong hai cách:

Nếu bạn truyền một pano_id, thì Map Tiles API sẽ trả về siêu dữ liệu cho ảnh toàn cảnh đó.
Nhưng nếu bạn truyền một lat và lng, thì Map Tiles API sẽ trả về siêu dữ liệu cho ảnh toàn cảnh gần nhất trong bán kính tìm kiếm đã cho.

Truyền một tập hợp toạ độ và bán kính

curl "https://tile.googleapis.com/v1/streetview/metadata?session=YOUR_SESSION_TOKEN&key=YOUR_API_KEY&lat=lat&lng=lng&radius=meters"

Vì mã ảnh toàn cảnh là tạm thời, nên bạn nên truyền một tập hợp toạ độ và giá trị radius trong yêu cầu siêu dữ liệu ban đầu của Chế độ xem đường phố. Để xem ví dụ, hãy xem đoạn mã sau.

curl "https://tile.googleapis.com/v1/streetview/metadata?session=YOUR_SESSION_TOKEN&key=YOUR_API_KEY&lat=47.62066&lng=-122.34923&radius=50"

Truyền panoId của hình ảnh trong Chế độ xem phố

curl "https://tile.googleapis.com/v1/streetview/metadata?session=YOUR_SESSION_TOKEN&key=YOUR_API_KEY&panoId=panoId"

Phản hồi siêu dữ liệu

Mã JSON sau đây là một ví dụ về phản hồi siêu dữ liệu thông thường.

{
 "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"
  }
 ]
}

Danh sách sau đây chứa định nghĩa của các trường trong nội dung phản hồi.

panoId: Mã nhận dạng duy nhất của ảnh toàn cảnh này. Bạn không nên dựa vào việc Mã ảnh toàn cảnh có hiệu lực lâu hơn một phiên hoạt động của người dùng.
lat, lng: Toạ độ (vĩ độ và kinh độ) của ảnh toàn cảnh. Các giá trị này có thể khác với toạ độ mà bạn đã truyền trong yêu cầu vì vị trí chụp nhanh đến ảnh toàn cảnh gần nhất.
imageHeight, imageWidth: Kích thước của hình ảnh toàn cảnh được ghép.
tileHeight, tileWidth: Kích thước của một ô ảnh toàn cảnh.
heading: Hướng la bàn, được đo bằng độ, theo chiều kim đồng hồ từ hướng Bắc. Hướng được trả về nằm trong phạm vi [0,360], trong đó 0 đại diện cho hướng Bắc.
tilt: Độ nghiêng của ảnh toàn cảnh, được đo bằng độ từ cực nam của ảnh toàn cảnh đến đường chân trời. Các giá trị được trả về nằm trong phạm vi [0, 180]. Giá trị 90 độ cho biết đường chân trời đã được căn chỉnh ở đường xích đạo của ảnh toàn cảnh.
roll: Góc xoay theo chiều kim đồng hồ quanh đường ngắm đã được áp dụng cho ảnh toàn cảnh để cân bằng đường chân trời. Các giá trị được trả về nằm trong phạm vi [0, 360].
imageryType: Cho biết loại hình ảnh. Các giá trị hợp lệ là indoor và outdoor.
date: Ngày chụp ảnh. Không phải tất cả hình ảnh đều có dữ liệu ngày. Nhưng khi có, trường này sẽ chứa sự kết hợp của năm (YYYY) và tháng (MM). Ví dụ: 2023-05 hoặc 2024.
copyright: Văn bản bản quyền mà bạn phải hiển thị dưới dạng thông tin ghi nhận cùng với hình ảnh trong Chế độ xem phố.
reportProblemLink: Một siêu liên kết để người dùng sử dụng nhằm báo cáo vấn đề với ô Chế độ xem phố này. Bạn phải hiển thị siêu liên kết này ở góc dưới cùng bên phải của hình ảnh và siêu liên kết này phải chứa văn bản liên kết có nội dung như "Báo cáo vấn đề với hình ảnh này".
addressComponent: Một Geocode có cấu trúc chứa thông tin chi tiết về địa chỉ của ảnh toàn cảnh. Để biết thêm thông tin, xem Yêu cầu và phản hồi về mã hoá địa lý trong tài liệu về Geocoding API.
links: Danh sách mã ảnh toàn cảnh liên kết đến mã này. Cũng chứa tiêu đề mà đường liên kết được tìm thấy. Ví dụ: nếu tiêu đề là 180°, thì ảnh toàn cảnh được liên kết sẽ ở phía nam của ảnh toàn cảnh hiện tại. Xin lưu ý rằng do tính chất tạm thời của mã ảnh toàn cảnh, bạn không nên dựa vào các mã này trong hơn một phiên hoạt động của người dùng.

Hình thu nhỏ của Chế độ xem đường phố

Bạn có thể yêu cầu hình ảnh trong Chế độ xem đường phố ở định dạng thumbnail. Hình thu nhỏ là hình ảnh không được chia ô có kích thước, tiêu đề, độ nghiêng và trường nhìn do người dùng xác định. Hình ảnh thu nhỏ có độ phân giải thấp hơn ô và có kích thước tệp nhỏ hơn. Bạn đưa ra yêu cầu hình thu nhỏ bằng cách gửi yêu cầu GET đến điểm cuối thumbnail, như minh hoạ trong nguyên mẫu mã sau.

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"

Hãy xem ví dụ về mã sau đây, mã này tải một hình thu nhỏ của hình ảnh trong Chế độ xem phố được chụp ở Whistler, Canada.

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

Thông số bắt buộc

panoId: Mã nhận dạng duy nhất của hình thu nhỏ mà bạn muốn. Bạn có thể nhận các giá trị mã ảnh toàn cảnh từ điểm cuối panoIds hoặc từ điểm cuối metadata. Cả hai điểm cuối này đều chấp nhận toạ độ địa lý và trả về panoId thích hợp.
session: Mã phiên hợp lệ.
key: Khoá API của bạn.

Thông số tùy chọn

height: Chỉ định chiều cao của hình thu nhỏ tính bằng pixel, từ 16 pixel đến 250 pixel. Nếu bạn không chỉ định chiều cao, thì chiều cao sẽ mặc định là giá trị tối đa được phép là 250 pixel. Nếu bạn chỉ định một giá trị nằm ngoài phạm vi, thì hình thu nhỏ sẽ chụp nhanh đến giá trị hợp lệ gần nhất.
width: Chỉ định chiều rộng của hình thu nhỏ tính bằng pixel, từ 16 pixel đến 600 pixel. Nếu bạn không chỉ định chiều rộng, thì chiều rộng sẽ mặc định là giá trị tối đa được phép là 600 pixel. Nếu bạn chỉ định một giá trị nằm ngoài phạm vi, thì hình thu nhỏ sẽ chụp nhanh đến giá trị hợp lệ gần nhất.
pitch: Chỉ định góc của camera dọc theo trục dọc. Các giá trị hợp lệ nằm trong phạm vi từ -90 đến 90 (bao gồm cả hai giá trị này). Giá trị mặc định là 0.
yaw: Chỉ định hướng của camera dọc theo trục ngang. Các giá trị hợp lệ nằm trong phạm vi từ -360 đến 360 (bao gồm cả hai giá trị này). Giá trị mặc định là 0.
fov: Chỉ định trường nhìn ngang, được biểu thị bằng độ, với giá trị tối đa là 120. Khi xử lý khung nhìn có kích thước cố định, như với hình ảnh trong Chế độ xem phố có kích thước cố định, trường nhìn đại diện cho mức thu phóng; trong đó, các giá trị nhỏ hơn chỉ định mức thu phóng cao hơn. Giá trị mặc định là 90.

Ô hình ảnh trong Chế độ xem phố

Sau khi có panoId, bạn có thể yêu cầu một ô hình ảnh trong Chế độ xem phố. Yêu cầu ô là yêu cầu GET HTTPS. Hãy xem ví dụ sau đây.

curl "https://tile.googleapis.com/v1/streetview/tiles/z/x/y?session=YOUR_SESSION_TOKEN&key=YOUR_API_KEY&panoId=panoId"

Trong ví dụ về mã này, z là mức thu phóng, còn x và y là tọa độ ô vuông của Ô Chế độ xem phố mà bạn muốn. Cấp thu phóng trong ảnh toàn cảnh của Chế độ xem phố phải nằm trong phạm vi [0,5], trong đó 0 đại diện cho trường nhìn rộng nhất.

Cấp thu phóng	Trường nhìn gần đúng
0	360°
1	180°
2	90°
3	45°
4	22,5°
5	11,25°

Phản hồi Ô Chế độ xem phố

Yêu cầu ô Chế độ xem phố thành công sẽ trả về một hình ảnh có định dạng và kích thước mà bạn đã chỉ định trong phản hồi createSession.

Kết quả của một yêu cầu thành công về ô

Ở mức thu phóng 0, toàn bộ ảnh toàn cảnh sẽ được đổi kích thước thành một ô có kích thước tileWidth x tileHeight. Vì ảnh toàn cảnh có kích thước lớn hơn theo chiều x, nên ô sẽ chứa khoảng trống theo chiều y:

Mức thu phóng bằng 0

Ở mức thu phóng 5, ảnh toàn cảnh có kích thước đầy đủ sẽ được sử dụng và chia thành các ô.

x

Thông tin bản quyền

Bạn phải hiển thị thông tin bản quyền với mọi ảnh toàn cảnh trong Chế độ xem đường phố. Chuỗi cần hiển thị có thể khác nhau giữa các ảnh toàn cảnh. Để nhận thông tin bản quyền, bạn phải yêu cầu siêu dữ liệu của Chế độ xem đường phố, sau đó, bạn có thể tham khảo trường copyright trong phản hồi. Để biết thêm thông tin, hãy xem Thông tin ghi nhận dữ liệu.