Thẻ thông tin Chế độ xem đường phố tương tự như Thẻ thông tin 2D, ngoại trừ việc các thẻ này 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, nhà thi đấu, nhà hàng hoặc doanh nghiệp nhỏ.
Điểm cuối API này cấp cho bạn quyền truy cập vào:
- Ô Chế độ xem phố của Google Maps
- Siêu dữ liệu của Chế độ xem đường phố
- Hình thu nhỏ của Chế độ xem phố
Bạn có thể ghép các ô hình ảnh lại với nhau được chụp ở cấp đường phố để tạo ra hiệu ứng toàn cảnh như thật. Bạn có thể truy vấn tối đa 100 mã nhận dạng ảnh toàn cảnh cho một nhóm vị trí (chẳng hạn như một tuyến đường) cũng như nhận siêu dữ liệu chuyên sâu hơn về vị trí của máy ảnh.
Cần có người xem để ghép các Thẻ thông tin trong Chế độ xem đường phố với nhau. Ví dụ: trình xem ảnh toàn cảnh tuỳ chỉnh trong 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ã 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 ả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 của phản hồi tìm kiếm ảnh toàn cảnh để nhận được:
Siêu dữ liệu của Chế độ xem đường phố. Bạn cũng có thể xem siêu dữ liệu Chế độ xem đường phố bằng cách truyền một nhóm toạ độ và bán kính.
Phương thức Chế độ xem 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 | Nội dung mô tả |
|---|---|
https://tile.googleapis.com/v1/streetview/tiles |
Trả về từng ô trong Chế độ xem đường phố. Bạn có thể truy xuất các Ô Chế độ xem phố ở sáu 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 tối đa 100 vị trí hàng loạt. Trả về mã ảnh toàn cảnh cho tất 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 đề, lượt đề cử, 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. Các chi tiết bao gồm địa chỉ có liên quan và liên kết đến ảnh toàn cảnh liền kề. |
Tìm kiếm ảnh toàn cảnh trong 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) vào phương thức panoIds. Nội dung yêu cầu là một đối tượng JSON có chứa mảng locations và (không bắt buộc) 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
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 giá trị khác, tối đa là 100 bộ. 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 một vị trí nhất định, dùng để tìm kiếm ảnh toàn cảnh. Giá trị mặc định là 50 mét.
Phản hồi PanoId
API Thẻ thông tin bản đồ 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 toàn cảnh của chúng. Yêu cầu panoIds thành công sẽ trả về một đối tượng JSON chứa mảng panoIds. Mảng này chứa danh sách mã nhận dạng toàn cảnh, theo thứ tự bạn yêu cầu các mã đó. Nếu API Thẻ thông tin bản đồ không thể tìm thấy bất kỳ ả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. Để biết 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ỏ ở Chế độ xem đường phố
- Yêu cầu thẻ thông tin trong Chế độ xem đường 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 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ì API Thẻ thông tin của bản đồ sẽ trả về siêu dữ liệu cho ảnh toàn cảnh đó.Tuy nhiên, nếu bạn truyền
latvàlng, thì API Thẻ thông tin của bản đồ 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 nhất định.
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ận dạng ảnh toàn cảnh là tạm thời, 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ố.
Để biết 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 ảnh toàn cảnh 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 của siêu dữ liệu
Mã JSON sau đây là 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 Mã nhận dạng ảnh toàn cảnh có hiệu lực lâu 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 đã chuyển vào yêu cầu vì vị trí gắn vào ảnh toàn cảnh gần nhất.
imageHeight,imageWidth- Kích thước của ảnh toàn cảnh được ghép nối.
tileHeight,tileWidth- Kích thước của một ô 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. Các tiêu đề được trả về trong phạm vi [0,360], với 0 biểu thị cho đến hạn ở 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 tại đường xích đạo của ảnh toàn cảnh.
roll- Chế độ xoay theo chiều kim đồng hồ xung quanh đường nhìn được áp dụng cho ảnh toàn cảnh để cân bằng đường chân trời. Các giá trị 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 ngày. Nhưng khi được cung cấp, trường này sẽ chứa cả 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 sự đóng góp cùng với hình ảnh trong Chế độ xem đường phố.
reportProblemLink- Một siêu liên kết để người dùng sử dụng để báo cáo sự cố liên quan đến thẻ thông tin 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à nó phải bao gồm văn bản liên kết có nội dung như "Báo cáo vấn đề về hình ảnh này".
addressComponent- 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 phần Yêu cầu và phản hồi mã hoá địa lý trong tài liệu về API mã hoá địa lý.
links- Danh sách mã ảnh toàn cảnh liên kết với ảnh này. Ngoài ra còn chứa tiêu đề nơi tìm thấy đường liên kết. 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. Lưu ý rằng do tính chất tạm thời của mã nhận dạng ảnh toàn cảnh, bạn không nên dựa vào các mã này nhiều hơn một phiên người dùng.
Hình thu nhỏ của Chế độ xem 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à các hình ảnh không xếp kề, có kích thước, tiêu đề, độ cao và trường nhìn do người dùng xác định.
Hình ảnh hì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 xét ví dụ về mã sau đây: tải xuống hình thu nhỏ của hình ảnh trong 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ỏ bạn muốn. Bạn có thể nhận giá trị mã nhận dạng ảnh toàn cảnh từ điểm cuối
panoIdshoặc từ điểm cuốimetadata– cả hai điểm cuối đều chấp nhận toạ độ địa lý và trả vềpanoIdthích hợp. session- 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, trong khoảng 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 sử dụng giá trị tối đa cho phép là 250 pixel. Nếu bạn chỉ định một giá trị nằm ngoài phạm vi, hình thu nhỏ sẽ gắn liền với 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, trong khoảng 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 dùng 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ẽ gắn liền với giá trị hợp lệ gần nhất.
pitch- Chỉ định góc của camera dọc theo trục tung. Các giá trị hợp lệ nằm trong phạm vi từ
-90đến90(bao gồm). Giá trị mặc định là 0. yaw- Chỉ định hướng của máy ảnh dọc theo trục hoành. Các giá trị hợp lệ nằm trong phạm vi từ
-360đến360(bao gồm). Giá trị mặc định s 0. fov- Chỉ định trường nhìn theo chiều ngang, 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, chẳng hạn như với hình ảnh Chế độ xem đường phố có kích thước đã đặt, trường nhìn thể hiện mức thu phóng; trong đó 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 đường phố. Yêu cầu thẻ thông tin là các 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 độ ô của ô Chế độ xem đường phố mà bạn muốn. Mức thu phóng trong ảnh toàn cảnh của Chế độ xem đường phố phải nằm trong phạm vi [0,5], với 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° |
Phản hồi về các ô trong Chế độ xem đường phố
Yêu cầu thành công ô Chế độ xem đường phố sẽ trả về 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 được đổi kích thước thành ô có kích thước tileWidth x tileHeight. Vì ảnh toàn cảnh lớn hơn theo kích thước x, nên thẻ thông tin sẽ chứa không gian trống trong kích thước y:
Ở mức thu phóng 5, ảnh toàn cảnh với kích thước đầy đủ được sử 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 hiển thị có thể khác nhau giữa các ảnh toàn cảnh. Để xem thông tin bản quyền, bạn phải yêu cầu siêu dữ liệu Chế độ xem đường phố, sau đó có thể tham khảo trường copyright của câu trả lời. Để biết thêm thông tin, hãy xem bài viết Phân bổ dữ liệu.