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

Giới thiệu

Yêu cầu siêu dữ liệu của Street View Static API cung cấp dữ liệu về ảnh toàn cảnh trong Chế độ xem đường phố. Bằng cách sử dụng siêu dữ liệu, bạn có thể biết liệu hình ảnh trong Chế độ xem đường phố có sẵn 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 toạ độ 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 lỗi trong ứng dụng.

Lưu ý: Giá trị của trường ngày có thể khác nhau:

• Trường ngày có thể có mức độ chi tiết khác nhau cho các ảnh toàn cảnh khác nhau. Ví dụ: trường ngày cho một số ảnh toàn cảnh chứa năm và tháng, trong khi đối với những ảnh khác, trường này chỉ chứa năm.
• Trường ngày sẽ bị bỏ qua nếu không có dữ liệu.

Bạn có thể gửi yêu cầu siêu dữ liệu Chế độ xem đường phố Static API mà không mất phí. Bạn không bị tính hạn mức khi 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 Chế độ xem đường phố tĩnh.

Khi đưa ra yêu cầu về 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 trong phạm vi 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 loại HTTP có dạng như sau:

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

Lưu ý: giao thức https:// là bắt buộc đối với các yêu cầu siêu dữ liệu.

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

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

Yêu cầu siêu dữ liệu chấp nhận các tham số URL giống với yêu cầu hình ảnh của API tĩnh Chế độ xem đường phố, mặc dù chỉ cần các tham số sau:

Hãy thực hiện một trong hai 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 độ được phân tách bằng dấu phẩy (40.457375,-80.009353).

hoặc:

• pano – mã nhận dạng ảnh toàn cảnh cụ thể. Ảnh toàn cảnh có thể thay đổi mã nhận dạng 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 toạ độ vĩ độ và kinh độ để 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ận dạng ả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 là thông tin bắt buộc trong một số trường hợp và luôn được khuyến khích. Để biết thêm thông tin, hãy xem bài viết Lấy khoá và chữ ký.

Yêu cầu siêu dữ liệu của bạn (chỉ có 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=<YOUR_SIGNATURE>

hoặc như sau:

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

Làm mới mã nhận dạng ảnh toàn cảnh đã xoá

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

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

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

Lưu ý: Vì hình ảnh trong Chế độ xem đường phố được làm mới định kỳ và ảnh có thể được chụp từ các vị trí hơi khác nhau mỗi lần, nên một mã nhận dạng ảnh toàn cảnh nhất định có thể chuyển sang một ảnh toàn cảnh khác khi hình ảnh hoặc mã nhận dạng ảnh toàn cảnh được cập nhật.

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

Bạn có thể thêm các tham số sau vào yêu cầu siêu dữ liệu: size, heading, fov và pitch. Xin lưu ý rằng các tham 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 đưa vào các tham 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 yêu cầu siêu dữ liệu, API này sẽ bỏ qua các tham số không bắt buộc và giá trị của các tham số đó. Để biết thông tin về cách sử dụng các tham số này, hãy xem hướng dẫn dành cho nhà phát triển về Street View Static API.

Định dạng của 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 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 về hình ảnh, trong đó hình ảnh bị thiếu là hình ảnh 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

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 ảnh toàn cảnh không 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 về 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

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	Mô tả
"OK"	Cho biết không có lỗi nào 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 không 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ận dạng ảnh toàn cảnh không tồn tại hoặc không hợp lệ. Xem phần [Làm mới mã nhận dạng ảnh toàn cảnh đã xoá](#refresh-pano).
"NOT_FOUND"	Cho biết không tìm thấy chuỗi địa chỉ được 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 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 Street View Static API không được kích hoạt trong dự án Google Cloud Console chứa khoá API của bạn.
"INVALID_REQUEST"	Thường cho biết rằng các tham số truy vấn (địa chỉ, toạ độ vĩ độ và kinh độ hoặc thành phần) bị thiếu.
"UNKNOWN_ERROR"	Cho biết rằng yêu cầu không thể xử lý được do lỗi phía 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 Google Maps khác, hãy nhớ xem Trang hỗ trợ của API Maps.