Yêu cầu hình ảnh trong Chế độ xem đường phố là một URL HTTP có định dạng sau:
https://maps.googleapis.com/maps/api/streetview?parameters
Hình ảnh được chỉ định bằng các tham số yêu cầu. Theo tiêu chuẩn trong URL, tất cả tham số được phân tách bằng ký tự ký hiệu và (&). Dưới đây là danh sách các tham số được phép và giá trị có thể có.
Thông số 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
), đồng thời phải được mã hoá URL. Vì vậy, hãy chuyển đổi các địa chỉ như "City Hall, New York, NY" thành "City+Hall,New+New York,NY" trước khi bạn gửi yêu cầu. API tĩnh của Chế độ xem đường phố chụp ảnh toàn cảnh gần nhất với vị trí. Khi bạn cung cấp chuỗi văn bản địa chỉ, API có thể sử dụng một vị trí máy ảnh khác để hiển thị vị trí được chỉ định một cách chính xác hơn. Khi bạn cung cấp toạ độ (vĩ độ và kinh độ), API sẽ tìm kiếm trong bán kính 50 mét để tìm ảnh chụp gần vị trí gần nhất. 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,location
của bạn có thể chụp nhanh một ảnh toàn cảnh khác khi hình ảnh được cập nhật.
hoặc:
pano
là một mã ả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 trữ mã 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ư:
size
chỉ định kích thước đầu ra của hình ảnh tính bằng pixel. Kích thước được chỉ định là{width}x{height}
– ví dụ:size=600x400
trả về hình ảnh có chiều rộng 600 pixel và chiều cao 400 pixel.key
cho phép bạn giám sát mức sử dụng API của ứng dụng trong Google Cloud Console và đảm bảo rằng Google có thể liên hệ với bạn về ứng dụng nếu cần. Để biết thêm thông tin, hãy xem phần Lấy khoá và chữ ký.
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.
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.
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.
Thông số tùy chọn
signature
(đề xuất) là một chữ ký số dùng để xác minh rằng mọi trang web tạo yêu cầu bằng khoá API của bạn đều được phép làm như vậy. Những yêu cầu không có chữ ký số có thể không thành công. Để biết thêm thông tin, hãy xem phần Lấy khoá và chữ ký.Lưu ý: đối với những khách hàng từng sử dụng Gói Google Maps cao cấp, bạn bắt buộc phải có chữ ký số. Tìm hiểu thêm thông tin về các thông số xác thực dành cho khách hàng sử dụng Gói cao cấp.
heading
cho biết hướng la bàn của máy ảnh. Các giá trị được chấp nhận là từ0
đến360
(cả hai giá trị là hướng Bắc, trong đó90
là hướng Đông và180
là hướng Nam). Nếu bạn không chỉ định tiêu đề, thì một giá trị sẽ được tính để hướng máy ảnh đếnlocation
được chỉ định, từ thời điểm chụp ảnh gần nhất.fov
(mặc định là90
) xác định trường nhìn theo chiều ngang của hình ảnh được biểu thị bằng độ, với giá trị tối đa được phép là120
. Khi xử lý khung nhìn có kích thước cố định, giống như với hình ảnh Chế độ xem đường phố có kích thước đã đặt, về bản chất trường nhìn đại diện cho mức thu phóng, còn số nhỏ hơn cho biết mức thu phóng cao hơn.
(Trái:fov=120
; Phải:fov=20
)pitch
(mặc định là0
) chỉ định góc lên hoặc xuống của máy ảnh so với xe phục vụ Chế độ xem đường phố. Đây là trường hợp thường, nhưng không phải lúc nào cũng ngang. Giá trị dương giúp góc máy ảnh hướng lên trên (trong đó90
độ thể hiện hướng thẳng lên); giá trị âm hướng máy ảnh xuống (với-90
cho biết máy ảnh hướng thẳng xuống dưới).radius
(mặc định là50
) đặt bán kính (được chỉ định bằng mét) để tìm kiếm ảnh toàn cảnh, ở giữa vĩ độ và kinh độ đã cho. Giá trị hợp lệ là số nguyên không âm.return_error_code
cho biết liệu API có nên trả về mã lỗi khi không tìm thấy hình ảnh nào (404 NOT FOUND) hoặc để phản hồi một yêu cầu không hợp lệ (400 INVALID REQUEST). Các giá trị hợp lệ làtrue
vàfalse
. Nếu bạn đặt thànhtrue
, một thông báo lỗi sẽ được trả về thay cho hình ảnh màu xám chung. Khi đó, bạn không cần phải thực hiện lệnh gọi riêng để kiểm tra xem có hình ảnh nào không.source
(mặc định làdefault
) giới hạn lượt tìm kiếm trong Chế độ xem đường phố ở một số nguồn nhất định. Có các giá trị hợp lệ như sau:default
sử dụng các nguồn mặc định cho Chế độ xem đường phố; các lượt tìm kiếm không bị giới hạn ở các nguồn cụ thể.outdoor
giới hạn lượt tìm kiếm ở các bộ sưu tập ngoài trời. Các bộ sưu tập trong nhà không có trong kết quả tìm kiếm. Xin lưu ý rằng ảnh toàn cảnh ngoài trời có thể không tồn tại đối với vị trí được chỉ định. Ngoài ra, xin lưu ý rằng tính năng tìm kiếm chỉ trả về ảnh toàn cảnh khi có thể xác định là ảnh đang ở trong nhà hay ngoài trời. Ví dụ: PhotoSpheres không được trả về vì không xác định được đó là ảnh trong nhà hay ngoài trời.
Đây là một yêu cầu mẫu.
https://maps.googleapis.com/maps/api/streetview?size=600x300&location=46.414382,10.013988&heading=151.78&pitch=-0.76&key=YOUR_API_KEY&signature=YOUR_SIGNATURE
Không có hình ảnh nào
Đối với những vị trí không có hình ảnh trong Chế độ xem đường phố, API tĩnh của Chế độ xem đường phố sẽ trả về một hình ảnh chung màu xám với nội dung "Rất tiếc, chúng tôi không có hình ảnh ở đây.", như trong ví dụ sau:
Chỉ hiển thị hình ảnh hợp lệ
Để tránh hiển thị hình ảnh chung chung và đảm bảo rằng trang web của bạn chỉ hiển thị các hình ảnh API tĩnh của Chế độ xem đường phố hợp lệ, hãy làm theo các đề xuất sau:
- Đặt tham số
return_error_code
thànhtrue
. Điều này khiến API tĩnh của Chế độ xem đường phố trả về lỗi 404 NOT FOUND thay cho hình ảnh màu xám chung, nếu không có hình ảnh nào cho vị trí được chỉ định. - Yêu cầu siêu dữ liệu hình ảnh trong Chế độ xem đường phố để xác định xem có hình ảnh cho vị trí đã chỉ định hay không trước khi gửi yêu cầu.