Kiểu bản đồ mới sắp xuất hiện trên Nền tảng Google Maps. Bản cập nhật này để tạo kiểu bản đồ bao gồm một bảng màu mặc định mới và các cải tiến về trải nghiệm bản đồ cũng như khả năng hữu dụng. Tất cả kiểu bản đồ sẽ được cập nhật tự động vào tháng 3 năm 2025. Để biết thêm thông tin về phạm vi cung cấp và cách chọn tham gia sớm hơn, hãy xem bài viết Kiểu bản đồ mới cho Nền tảng Google Maps.

Trang này được dịch bởi Cloud Translation API.

Ô chế độ xem phố

Ví dụ về Chế độ xem đường phố Các ô trong Chế độ xem đường phố tương tự như Thẻ thông tin 2D ngoại trừ việc chúng chứa hình ảnh toàn cảnh được chụp ở cấp đường phố. Bằng 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à đi bộ bên trong những đị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 hiệu ứng toàn cảnh chân thực. Và bạn có thể truy vấn tối đa 100 ID ảnh toàn cảnh cho một tập hợp vị trí (chẳng hạn như một tuyến đường) và nhận siêu dữ liệu chuyên sâu hơn về camera vị trí.

Cần có người xem để ghép các Thẻ thông tin trong Chế độ xem đường phố với nhau. Ví dụ: Chế độ xem đường phố trình xem ảnh toàn cảnh tuỳ chỉnh.

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 đây.

Nhận mã thông báo phiên. Đảm bảo để đặt giá trị mapType thành streetview.
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 khu vực địa lý vị trí.
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:
1. Siêu dữ liệu của Chế độ xem đường phố. Bạn cũng có thể xem đường phố Xem siêu dữ liệu bằng cách truyền một toạ độ và bán kính.
2. Hình thu nhỏ trong Chế độ xem đường phố.
3. Thẻ thông tin trong Chế độ xem đường phố.

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

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

Phương thức	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ý theo truyền toạ độ (lat, lng) vào phương thức panoIds. Yêu cầu phần thân 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 mã JSON ví dụ 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 locations phải chứa ít nhất một bộ giá trị toạ độ, nhưng bạn có thể thêm nhiều hơn (tối đa 100).
radius: Giá trị radius (đo bằng mét) xác định bán kính của hình tròn xung quanh vị trí đã cho để 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 của bản đồ cố gắng tìm ảnh toàn cảnh gần nhất với từng vị trí và thì hệ thống sẽ trả về mã ảnh toàn cảnh. 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 toàn cảnh, theo thứ tự bạn yêu cầu. Nếu API Thẻ thông tin của 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, sau đó là một ảnh sẽ được trả về tại vị trí đó trong mảng. Để biết ví dụ, hãy xem sau mã JSON.

{
  "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. A Yêu cầu siêu dữ liệu lượt xem 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 URL đó ảnh toàn cảnh.
Tuy nhiên, nếu bạn truyền lat và lng thì API Thẻ thông tin của bản đồ sẽ trả về siêu dữ liệu để xem ả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"

Do 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à một giá trị radius trong yêu cầu siêu dữ liệu Chế độ xem đường phố ban đầu. Để 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 toàn cảnh có hiệu lực trong nhiều 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ể là khác với toạ độ mà bạn đã chuyển trong yêu cầu vì vị trí sẽ chụp thành ả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. Tiêu đề là được trả về trong phạm vi [0,360], trong đó 0 biểu thị cho đến hạn ở phía 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]. Một giá trị 90 độ cho biết rằng đường chân trời đã được căn chỉnh theo đường xích đạo của ảnh toàn cảnh.
roll: Độ xoay theo chiều kim đồng hồ xung quanh đường nhìn đã á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à indoor và 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ó sẵn, trường này 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 thuộc tính ghi nhận tác giả cùng với Đường phố Xem hình ảnh.
reportProblemLink: Một siêu liên kết để người dùng sử dụng để báo cáo sự cố 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 bên phải của hình ảnh và ảnh 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ới hình ảnh này".
addressComponent: A có cấu trúc Mã địa lý 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 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. Cũng chứa tiêu đề trên 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 là do phía nam của ảnh toàn cảnh hiện tại. Xin lưu ý rằng vì 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 để biết thêm so với một phiên người dùng duy nhất.

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ỏ hình ảnh không được xếp kề với kích thước, tiêu đề, độ cao 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 kích thước. Bạn đưa ra yêu cầu hình thu nhỏ bằng cách gửi yêu cầu GET tới thumbnail như được minh hoạ trong nguyên mẫu mã sau đây.

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ã tải xuống hình thu nhỏ của Chế độ xem phố sau đây hình ảnh đượ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 panoIds hoặc từ metadata điểm cuối – cả hai đều chấp nhận điểm cuối theo khu vực địa lý toạ độ và trả về panoId thí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 theo 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ẽ điều chỉnh theo 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 điểm ảnh. Nếu bạn không chỉ định chiều rộng, thì chiều rộng sẽ mặc định là chiều rộng tối đa giá trị cho 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ẽ điều chỉnh theo 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 đế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 máy ảnh dọc theo trục hoành. 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 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 giá trị 120. Khi xử lý khung nhìn có kích thước cố định, như với Chế độ xem phố hình ảnh có kích thước đã đặt, trường nhìn thể hiện 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 đường phố. Thẻ thông tin là các 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 và x và y là tọ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 phố phải nằm trong khoảng [0,5], với 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 về các ô trong Chế độ xem đường phố

Yêu cầu ô Chế độ xem phố thành công 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 của mình.

Kết quả của một yêu cầu Thẻ thông tin thành công

Ở mức thu phóng 0, toàn bộ ảnh toàn cảnh được đổi kích thước thành ô kích thước tileWidth của tileHeight. Do ảnh toàn cảnh lớn hơn theo kích thước x, ô sẽ chứa không gian trống trong kích thước y:

Mức thu phóng bằng 0

Ở 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ố. Chiến lược phát hành đĩa đơn để hiển thị có thể khác nhau giữa các ảnh toàn cảnh. Cách xem thông tin về bản quyền: bạn phải yêu cầu siêu dữ liệu Chế độ xem phố, sau đó bạn có thể hãy tham khảo trường copyright của phản hồi. Để biết thêm thông tin, hãy xem Phân bổ dữ liệu.