Ô Chế độ xem đường 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 đường phố của Google Maps
- Siêu dữ liệu của Chế độ xem đường phố
- Hình thu nhỏ trong 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ư ngoài đời thực. Bạn có thể truy vấn tối đa 100 mã nhận dạng toàn cảnh cho một nhóm vị trí (chẳng hạn như một tuyến đường) và nhận được siêu dữ liệu chi tiết hơn về vị trí camera.
Bạn cần có một trình xem để ghép các Ô Chế độ xem đường phố lại với nhau. Ví dụ: trình xem ảnh toàn cảnh tuỳ chỉnh Chế độ xem đường phố.
Sau khi có khoá API, bạn có thể truy cập vào hình ảnh Chế độ xem đường phố bằng cách thực hiện các bước sau.
Lấy mã thông báo phiên. Hãy nhớ đặt giá trị của
mapTypethànhstreetview.Sử dụng mã thông báo phiên để lấy giá trị nhận dạng 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 trong phản hồi tìm kiếm panoId để nhận:
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 đường phố bằng cách truyền một tập hợp các toạ độ và bán kính.
Các phương thức của Chế độ xem đường phố
Bạn có thể truy cập vào hình ảnh và siêu dữ liệu trong Chế độ xem đường phố 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ề từng ô Chế độ xem đường phố. Bạn có thể truy xuất các ô Chế độ xem đường phố ở 6 mức 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ận dạng 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 hướng, độ dốc, kích thước và góc 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 lân cận. |
Tìm kiếm panoId trong Chế độ xem đường phố
Bạn có thể tìm thấy mã nhận dạng 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ỳ chọn là radius, như minh hoạ trong ví dụ về mã JSON sau đây.
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
locationsphải chứa ít nhất một bộ giá trị toạ độ, nhưng bạn có thể thêm nhiều bộ giá trị hơn (tối đa 100 bộ). radius- Giá trị
radius(được đo bằng mét) xác định bán kính của hình 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 từng vị trí, sau đó trả về mã nhận dạng ả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ận dạng 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. Ví dụ: hãy xem mã JSON sau đây.
{
"panoIds": [
"ACfH-n2HcBvRry_3oc9grw",
"f5DJZatBAAAXHlooS2wKbw",
""
]
}
Bạn có thể sử dụng panoIds để:
- Yêu cầu siêu dữ liệu Chế độ xem đường phố
- Yêu cầu hình thu nhỏ của Chế độ xem đường phố
- Yêu cầu Ô Chế độ xem đường phố
Siêu dữ liệu của Chế độ xem đường phố
Các yêu cầu về siêu dữ liệu của Chế độ xem đường phố sẽ 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 đường phố là một yêu cầu HTTPS GET. 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 toàn cảnh đó.Nhưng nếu bạn truyền
latvà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 các 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ận dạng toàn cảnh chỉ là tạm thời, nên bạn nên truyền một tập hợp các toạ độ và giá trị radius trong yêu cầu siêu dữ liệu ban đầu về Chế độ xem đường phố.
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 một hình ảnh trong Chế độ xem đường 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
Đoạn 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 về 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 Panorama ID hợp lệ trong thời gian dài hơn một phiên 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í sẽ được điều chỉnh cho phù hợp với ả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, đo bằng độ, theo chiều kim đồng hồ từ hướng Bắc. Tiêu đề được trả về trong phạm vi [0,360], trong đó 0 biểu thị 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à
indoorvàoutdoor. date- Ngày chụp ảnh. Không phải hình ảnh nào cũng có dữ liệu về ngày tháng. Nhưng khi có sẵn, trường này sẽ chứa tổ hợp 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 quyền tác giả cùng với hình ảnh Chế độ xem đường phố.
reportProblemLink- Một siêu liên kết để người dùng sử dụng khi báo cáo vấn đề về ô Chế độ xem đường 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 có văn bản liên kết như "Báo cáo vấn đề về hình ảnh này".
addressComponent- Một Mã địa lý 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, hãy 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ận dạng toàn cảnh liên kết đến mã nhận dạng 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ẽ nằm ở 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ận dạng toàn cảnh, bạn không nên dựa vào các mã nhận dạng này trong hơn một phiên người dùng.
Hình thu nhỏ trong 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 xếp thành ô với kích thước, tiêu đề, độ nghiêng và trường nhìn do người dùng xác định.
Hình thu nhỏ có độ phân giải thấp hơn các ô và có kích thước tệp nhỏ hơn. Bạn đưa ra yêu cầu về 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 xét ví dụ về mã sau đây, mã này tải một hình thu nhỏ của hình ảnh Chế độ xem đường 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ận dạng toàn cảnh từ điểm cuối
panoIdshoặc từ điểm cuốimetadata. Cả hai điểm cuối này đều chấp nhận toạ độ địa lý và trả vềpanoIdthích hợp. session- Một mã thông báo 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 mặc định sẽ 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 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 mặc định sẽ 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 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 khoảng từ
-90đến90(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đến360(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ý một khung hiển thị có kích thước cố định, chẳng hạn như hình ảnh Chế độ xem đường phố có kích thước cố định, trường nhìn biểu thị 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 đường phố
Sau khi có panoId, bạn có thể yêu cầu một ô hình ảnh trong Chế độ xem đường phố. Yêu cầu về ô là yêu cầu HTTPS GET. 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à toạ độ ô của ô Chế độ xem đường phố mà bạn muốn. Mức thu phóng trong ảnh toàn cảnh ở Chế độ xem đường phố phải nằm trong khoảng [0,5], trong đó 0 thể hiện 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° |
Câu trả lời về Ô Chế độ xem đường phố
Yêu cầu thành công về ô Chế độ xem đường phố 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.
Ở 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ẽ có khoảng trống theo chiều y:
Ở mức thu phóng 5, ảnh toàn cảnh có kích thước đầy đủ sẽ được dùng và chia thành các ô.
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. Để lấy 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 bài viết Thông tin ghi nhận quyền sở hữu dữ liệu.