Siêu dữ liệu hình ảnh trong Chế độ xem đường phố

Giới thiệu

Các yêu cầu siêu dữ liệu API tĩnh của Chế độ xem đường phố cung cấp dữ liệu về ảnh toàn cảnh của Chế độ xem đường phố. Bằng cách sử dụng siêu dữ liệu, bạn có thể tìm hiểu xem hình ảnh trong Chế độ xem đường phố có được cung cấp tại một vị trí nhất định hay không, cũng như nhận quyền truy cập có lập trình vào vĩ độ và kinh độ, mã nhận dạng ảnh toàn cảnh, ngày chụp ảnh và thông tin bản quyền của hình ảnh. Việc truy cập vào siêu dữ liệu này cho phép bạn tuỳ chỉnh hành vi của lỗi trong ứng dụng của mình.

Bạn có thể sử dụng miễn phí các yêu cầu về siêu dữ liệu API tĩnh của Chế độ xem đường phố. Không có hạn mức nào được sử dụng khi bạn yêu cầu siêu dữ liệu. Hạn mức chỉ được sử dụng khi bạn tải một hình ảnh bằng API tĩnh của Chế độ xem đường phố.

Khi đưa ra yêu cầu siêu dữ liệu hình ảnh trong Chế độ xem đường phố, hình ảnh toàn cảnh sẽ chính xác đến 50 mét.

Truy cập vào siêu dữ liệu hình ảnh

Yêu cầu siêu dữ liệu hình ảnh trong Chế độ xem đường phố là một URL HTTP có dạng sau:

https://maps.googleapis.com/maps/api/streetview/metadata?parameters

Theo tiêu chuẩn trong URL, tất cả tham số được phân tách bằng ký tự dấu và (&).

Tham số bắt buộc cho yêu cầu siêu dữ liệu

Các yêu cầu siêu dữ liệu chấp nhận cùng một tham số URL như các yêu cầu hình ảnh API tĩnh của Chế độ xem đường phố, mặc dù chỉ có các tham số sau đây là bắt buộc:

Hãy thực hiện một trong các thao tác sau:

  • location – có thể là một chuỗi văn bản (chẳng hạn như Chagrin Falls, OH) hoặc một cặp toạ độ vĩ độ và kinh độ (40.457375,-80.009353) được phân tách bằng dấu phẩy.

hoặc:

  • pano — một mã nhận dạng ảnh toàn cảnh cụ thể. Ảnh toàn cảnh có thể thay đổi mã theo thời gian, vì vậy, đừng lưu giữ mã nhận dạng này. Thay vào đó, hãy lưu địa chỉ vị trí hoặc vĩ độ và kinh độ để bạn có thể làm mới mã nhận dạng ảnh toàn cảnh. Để biết thông tin chi tiết, hãy xem phần Làm mới mã ảnh toàn cảnh đã xoá.

Cũng như:

  • key và signature – cần có khoá API để xác thực yêu cầu. Chữ ký số cũng bắt buộc trong một số trường hợp và luôn nên dùng. Để biết thêm thông tin, hãy xem phần Lấy khoá và chữ ký.

Yêu cầu siêu dữ liệu của bạn (chỉ với các tham số bắt buộc) sẽ có dạng như sau:

https://maps.googleapis.com/maps/api/streetview/metadata?location=&key=YOUR_API_KEY&signature=

hoặc như thế này:

https://maps.googleapis.com/maps/api/streetview/metadata?pano=&key=YOUR_API_KEY&signature=

Làm mới mã ảnh toàn cảnh đã xoá

Nếu bạn cố gắng truy xuất mã ảnh toàn cảnh và nhận được ZERO_RESULTS hoặc không có giá trị nào, thì mã này đã bị xoá và bạn cần làm mới.

  1. Lưu địa chỉ vị trí hoặc vĩ độ và kinh độ mà bạn đã dùng để lấy mã nhận dạng ảnh toàn cảnh để bạn có thể làm mới khi cần.

  2. Khi bạn phát hiện mã nhận dạng ảnh toàn cảnh đã thay đổi, hãy sử dụng địa chỉ vị trí gốc hoặc toạ độ theo vĩ độ và kinh độ để tìm lại ảnh toàn cảnh gần nhất đến vị trí đó và nhận mã nhận dạng ảnh toàn cảnh mới.

Tham số không bắt buộc cho yêu cầu siêu dữ liệu

Bạn có thể đưa các tham số sau vào yêu cầu siêu dữ liệu: size, heading, fov và pitch. Lưu ý rằng các thông số này không ảnh hưởng đến dữ liệu về ảnh toàn cảnh hoặc ảnh toàn cảnh nào được tìm thấy. API này cho phép thêm các tham số tương tự như yêu cầu hình ảnh để giúp dễ dàng hơn trong việc tạo yêu cầu siêu dữ liệu liên quan đến một yêu cầu hình ảnh cụ thể, nhưng đối với các yêu cầu siêu dữ liệu, API sẽ bỏ qua các tham số không bắt buộc và giá trị của các yêu cầu đó. Để biết thông tin về cách sử dụng các thông số này, hãy xem Hướng dẫn dành cho nhà phát triển về API Tĩnh của Chế độ xem đường phố.

Định dạng phản hồi

Phản hồi của siêu dữ liệu chỉ được trả về ở định dạng JSON.

Ví dụ

Ví dụ 1: Tìm thấy ảnh toàn cảnh

Các URL sau đây yêu cầu thành công siêu dữ liệu và hình ảnh của cùng một ảnh toàn cảnh.

Yêu cầu và phản hồi siêu dữ liệu

https://maps.googleapis.com/maps/api/streetview/metadata?size=600x300&location=eiffel%20tower,%20paris,%20france&heading=-45&pitch=42&fov=110&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

{
   "copyright" : "© 2017 Google",
   "date" : "2016-05",
   "location" : {
      "lat" : 48.85783227207914,
      "lng" : 2.295226175151347
   },
   "pano_id" : "tu510ie_z4ptBZYo2BGEJg",
   "status" : "OK"
}

Yêu cầu và phản hồi hình ảnh, trong đó dự kiến sẽ có hình ảnh bị thiếu.

https://maps.googleapis.com/maps/api/streetview?size=600x300&location=eiffel%20tower,%20paris,%20france&heading=-45&pitch=42&fov=110&key=YOUR_API_KEY&signature=YOUR_SIGNATURE
Tháp Eiffel

Ví dụ 2: Không tìm thấy ảnh toàn cảnh

Các URL sau đây yêu cầu siêu dữ liệu và hình ảnh cho một ảnh toàn cảnh không thể tìm thấy tại hoặc gần vị trí đã chỉ định.

Yêu cầu và phản hồi siêu dữ liệu

https://maps.googleapis.com/maps/api/streetview/metadata?size=600x300&location=78.648401,14.194336&fov=90&heading=235&pitch=10&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

{
   "status" : "ZERO_RESULTS"
}

Yêu cầu và phản hồi hình ảnh

https://maps.googleapis.com/maps/api/streetview?size=600x300&location=78.648401,14.194336&fov=90&heading=235&pitch=10&key=YOUR_API_KEY&signature=YOUR_SIGNATURE
Phần giữ chỗ không có hình ảnh

Mã trạng thái

Trường status trong đối tượng phản hồi siêu dữ liệu chứa trạng thái của yêu cầu và có thể chứa thông tin gỡ lỗi để giúp bạn khắc phục sự cố khiến yêu cầu Chế độ xem đường phố không hoạt động. Trường status có thể chứa các giá trị sau:

Trạng thái Nội dung mô tả
"OK" Cho biết rằng không có lỗi nào xảy ra; tìm thấy ảnh toàn cảnh và siêu dữ liệu được trả về.
"ZERO_RESULTS" Cho biết rằng không thể tìm thấy ảnh toàn cảnh nào gần vị trí đã cung cấp. Phản hồi này có thể xảy ra nếu bạn cung cấp mã ảnh toàn cảnh không tồn tại hoặc không hợp lệ. Xem [Làm mới các mã ảnh toàn cảnh đã xoá](#refresh-pano).
"NOT_FOUND" Cho biết rằng không thể tìm thấy chuỗi địa chỉ mà bạn cung cấp trong tham số location. Thông báo này có thể xuất hiện nếu bạn cung cấp một địa chỉ không tồn tại.
"OVER_QUERY_LIMIT" Cho biết rằng bạn đã vượt quá hạn mức hằng ngày hoặc hạn mức mỗi giây cho API này.
"REQUEST_DENIED" Cho biết rằng yêu cầu của bạn bị từ chối. Thông báo này có thể xuất hiện nếu bạn không uỷ quyền cho yêu cầu của mình hoặc nếu API tĩnh của Chế độ xem đường phố chưa được kích hoạt trong dự án Google Cloud Console chứa khoá API của bạn.
"INVALID_REQUEST" Thường chỉ ra rằng các tham số truy vấn (địa chỉ, vĩ độ và kinh độ hoặc thành phần) bị thiếu.
"UNKNOWN_ERROR" Cho biết rằng không thể xử lý yêu cầu do lỗi máy chủ. Vấn đề này thường chỉ là tạm thời. Yêu cầu có thể thành công nếu bạn thử lại.

Thông tin khác

Để biết thêm thông tin về cách sử dụng API tĩnh của Chế độ xem đường phố hoặc các sản phẩm API khác của Google Maps, hãy xem trang hỗ trợ của API Maps.