Giới thiệu
Các yêu cầu siêu dữ liệu API tĩnh cho Chế độ xem đường phố cung cấp dữ liệu về Đường phố Xem ảnh toàn cảnh. Nhờ sử dụng siêu dữ liệu, bạn có thể biết được liệu một hình ảnh trong Chế độ xem đường phố hoạt động tại một vị trí nhất định, 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 đó. Truy cập siêu dữ liệu cho phép bạn tuỳ chỉnh hành vi lỗi trong ứng dụng của mình.
Yêu cầu siêu dữ liệu API tĩnh cho Chế độ xem đường phố mà không có sạc. 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 dành cho 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 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ý hiệ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 tham số URL giống nhau như yêu cầu về hình ảnh API tĩnh cho Chế độ xem phố, mặc dù chỉ các tham số sau đây là bắt buộc:
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ột mã ả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à đừng duy trì mã này. Thay vào đó, hãy lưu địa chỉ của 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. Cho chi tiết, xem Làm mới ID ảnh toàn cảnh đã xóa.
Cũng như:
key
vàsignature
– bắt buộc phải có khoá API để xác thực của bạn. Chữ ký số cũng bắt buộc trong một số trường hợp, và luôn được khuyến nghị. Để biết thêm thông tin, hãy xem Mua 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ư thế này:
https://maps.googleapis.com/maps/api/streetview/metadata?pano=&key=YOUR_API_KEY&signature=<YOUR_SIGNATURE>
Làm mới mã ảnh toàn cảnh đã xoá
Nếu bạn cố gắng truy xuất ID ảnh toàn cảnh và nhận được ZERO_RESULTS
hoặc
không có giá trị, thì mã toàn cảnh đã bị xoá và cần được làm mới.
Lưu địa chỉ vị trí hoặc toạ độ theo vĩ độ và kinh độ mà bạn đã dùng để nhận mã nhận dạng ảnh toàn cảnh để bạn có thể làm mới khi cần.
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 vị trí ban đầu hoặc vĩ độ và kinh độ để tìm kiếm lại vị trí gần nhất ảnh toàn cảnh vào vị trí đó và nhận ID ảnh toàn cảnh mới.
Thông 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 của mình: size
,
heading
, fov
và pitch
. 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 tìm thấy ảnh toàn cảnh nào.
API này cho phép đưa vào các tham số giống như
yêu cầu hình ảnh
để tạo yêu cầu siêu dữ liệu liên quan đến một hình ảnh cụ thể dễ dàng hơn
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 họ. Để 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 API Chế độ xem đường phố tĩnh.
Định dạng câu trả lờ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 đó 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
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 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 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ố
lý do 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; sẽ tìm thấy một ảnh toàn cảnh và siêu dữ liệu bị trả lại. |
"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 chuỗi địa chỉ được cung cấp trong location
không thể tìm thấy thông số. Có thể thông báo này sẽ xuất hiện nếu đị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 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 yêu cầu của bạn hoặc nếu API tĩnh của Chế độ xem phố không được kích hoạt trong Dự án trên Google Cloud Console chứa khoá API của bạn. |
"INVALID_REQUEST" |
Nói chung cho biết rằng các tham số truy vấn (địa chỉ, vĩ độ và kinh độ) 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 phố, hoặc các sản phẩm API Google Maps khác, hãy nhớ xem API Maps Trang hỗ trợ.