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

Giới thiệu

Yêu cầu siêu dữ liệu API Chế độ xem phố cung cấp dữ liệu về ảnh toàn cảnh của Chế độ xem phố. Bằng cách sử dụng siêu dữ liệu, bạn có thể tìm hiểu xem có hình ảnh Chế độ xem phố tại một vị trí nhất định hay không, cũng như có quyền truy cập có lập trình vào vĩ độ và kinh độ, mã ả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ác yêu cầu siêu dữ liệu API tĩnh của Chế độ xem phố được cung cấp miễn phí. Không có định 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 hình ảnh bằng API tĩnh của Chế độ xem phố.

Khi đưa ra yêu cầu siêu dữ liệu hình ảnh ở Chế độ xem phố, ả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 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ả các tham số được phân tách bằng ký tự "@".

Các tham số bắt buộc đối với 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ác thông số URL giống nhau như các yêu cầu hình ảnh trong API tĩnh của Chế độ xem phố, mặc dù chỉ có các thông số sau 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 tọa độ vĩ độ/kinh độ được phân tách bằng dấu phẩy (40.457375,-80.009353).

hoặc:

  • pano — một mã ảnh toàn cảnh cụ thể. Các ảnh này thường ổn định, mặc dù ảnh toàn cảnh có thể thay đổi mã nhận dạng theo thời gian khi hình ảnh được làm mới.

Cũng như:

  • keysignature — cần phải có khoá API để xác thực yêu cầu. Trong một số trường hợp, bạn cũng bắt buộc phải sử dụng chữ ký số và phải luôn sử dụng chữ ký số này. Để biết thêm thông tin, hãy xem phần Nhận 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ẽ trông như sau:

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

hoặc như sau:

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

Các 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, fovpitch. Xin 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 được tìm thấy. API này cho phép thêm các thông số giống như yêu cầu hình ảnh để giúp bạn dễ dàng 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ể. Tuy nhiên, đối với các yêu cầu siêu dữ liệu, API sẽ bỏ qua các thông số không bắt buộc và giá trị của các thông số đó. Xem hướng dẫn dành cho nhà phát triển API tĩnh của Chế độ xem phố để biết thông tin về cách sử dụng các thông số này.

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

Phản hồi 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 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 về hình ảnh, trong đó hình ảnh bị thiếu dự kiến.

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 toàn cảnh không thể tìm thấy tại hoặc gần vị trí được 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
Không có phần giữ chỗ cho hình ảnh tại đây

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 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 không có lỗi xảy ra; tìm thấy ảnh toàn cảnh và trả về siêu dữ liệu.
"ZERO_RESULTS" Cho biết rằng không thể tìm thấy ảnh toàn cảnh gần vị trí đã cung cấp. Điều 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ệ.
"NOT_FOUND" Cho biết rằng hệ thống không tìm thấy chuỗi địa chỉ mà bạn cung cấp trong thông số location. Điều này có thể xảy ra nếu một địa chỉ không tồn tại đã được cung cấp.
"OVER_QUERY_LIMIT" Cho biết rằng bạn đã vượt quá hạn mức hằng ngày hoặc định 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. Điều này có thể xảy ra nếu bạn không uỷ quyền yêu cầu của mình hoặc nếu API tĩnh của Chế độ xem phố không được kích hoạt trong dự án Google Cloud Console có chứa khóa API của bạn.
"INVALID_REQUEST" Nhìn chung, cho biết rằng các tham số truy vấn (địa chỉ hoặc vĩ độ hoặc thành phần) bị thiếu.
"UNKNOWN_ERROR" Cho biết rằng yêu cầu không thể được xử lý do lỗi máy chủ. Đây thường là trạng thái 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 phố hoặc các sản phẩm khác của API Google Maps, hãy nhớ xem Trang hỗ trợ của API Maps.