Phản hồi và yêu cầu liên quan đến Chế độ xem đường phố

Yêu cầu Hình ảnh trong Chế độ xem đường phố là một URL loại HTTP ở định dạng sau:

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

Hình ảnh này được chỉ định bằng các tham số yêu cầu. Như tiêu chuẩn trong URL, tất cả tham số được phân tách bằng ký tự "&". Dưới đây là danh sách các tham số được phép và giá trị có thể có của chúng.

Thông số 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 cặp toạ độ vĩ độ và kinh độ (40.457375,-80.009353), và phải được mã hoá URL. Vì vậy, hãy chuyển đổi các địa chỉ như "Thành phố, New York, NY" đến "Thành phố+Hall,New+New York,NY" trước khi gửi yêu cầu. API Chế độ xem phố tĩnh chụp nhanh ảnh toàn cảnh gần nhất vị trí đó. Khi bạn cung cấp một chuỗi văn bản địa chỉ, API có thể sử dụng vị trí máy ảnh khác để hiển thị tốt hơn vị trí được chỉ định. Khi bạn cung cấp toạ độ theo vĩ độ và kinh độ, API tìm kiếm một bức ảnh gần vị trí đó nhất trong bán kính 50 mét. Bởi vì hình ảnh trong Chế độ xem đường phố được làm mới định kỳ và ảnh chụp có thể được lấy từ các vị trí hơi khác nhau mỗi lần, có thể location có thể chụp ảnh toàn cảnh khác khi hình ảnh được cập nhật.

hoặc:

  • pano là một 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à đừ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. Để chi tiết, xem Làm mới ID ảnh toàn cảnh đã xóa.

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 sẽ trả về hình ảnh rộng 600 pixel và cao 400.
  • key cho phép bạn giám sát mức sử dụng API của ứng dụng trong Bảng điều khiển Google Cloud, và đảm bảo rằng Google có thể liên hệ với bạn về đơn đăng ký của bạn nếu cần. Để biết thêm thông tin, hãy xem bài viết Nhận 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 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.

  1. 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.

  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 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ố tùy chọn

  • signature (nên dùng) là chữ ký số được 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 đã được cấp phép để làm điều đó. Các yêu cầu không bao gồm chữ ký số có thể không thành công. Để biết thêm thông tin, hãy xem bài viết Nhận khoá và chữ ký.

    Lưu ý: đối với những khách hàng từng sử dụng Gói cao cấp của Nền tảng Google Maps, thì gói kỹ thuật số bắt buộc phải có chữ ký. Xem thêm thông tin về thông số xác thực cho Khách hàng sử dụng Gói cao cấp.

  • heading biểu thị hướng la bàn của máy ảnh. Các giá trị được chấp nhận là từ 0 đến 360 (cả hai giá trị đều chỉ ra Bắc, với 90 chỉ phía Đông và 180 phía Nam). Nếu bạn không chỉ định tiêu đề, giá trị sẽ là được tính toán để hướng camera về phía location, tính từ điểm mà ảnh gần nhất bắt đầu đã thực hiện.
  • 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ị theo độ, 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, như với hình ảnh Chế độ xem phố của kích thước tập hợp, trường nhìn về bản chất đại diện cho thu phóng, với các số nhỏ hơn cho biết mức độ thu phóng cao hơn.


    Ảnh chụp màn hình một trường nhìn trên phạm vi rộng, cho thấy trần, tường, sàn và cửa sổ bể cá bên trong một bể cá. Ảnh chụp màn hình trường nhìn cận cảnh, hiển thị chi tiết được phóng to của một ảnh ở Chế độ xem đường phố bên trong một bể cá.
    (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 Chế độ xem đường phố chiếc xe. Đây là định dạng ngang phẳng thường nhưng không phải lúc nào cũng hiển thị. Giá trị dương hướng camera lên (với 90 độ hiển thị là thẳng đứng); giá trị âm điều chỉnh góc độ camera xuống (với -90 biểu thị thẳng xuống).
  • radius (mặc định là 50) đặt bán kính, được chỉ định theo mét, để tìm kiếm ảnh toàn cảnh, ở giữa vĩ độ và kinh độ cho sẵn. Các giá trị hợp lệ là số không âm số nguyên.
  • return_error_code cho biết liệu API có trả về hay không 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 YÊU CẦU XẤU). Các giá trị hợp lệ là truefalse. Nếu bạn đặt chính sách này thành true, thông báo lỗi sẽ xuất hiện trả về thay cho hình ảnh màu xám chung. Nhờ vậy, bạn không cần phải thực hiện một cuộc 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 các tìm kiếm trong Chế độ xem đường phố ở các nguồn được chọn. Các giá trị hợp lệ là:
    • default sử dụng các nguồn mặc định cho Chế độ xem đường phố; lượt tìm kiếm không bị giới hạn ở những nguồn cụ thể.
    • outdoor giới hạn việc tìm kiếm ở các bộ sưu tập ngoài trời. Trong nhà bộ sưu tập không được đưa vào kết quả tìm kiếm. Lưu ý rằng ảnh toàn cảnh ngoài trời có thể không tồn tại cho vị trí được chỉ định. Ngoài ra, xin lưu ý rằng tìm kiếm chỉ trả về ảnh toàn cảnh nơi có thể xác định xem chúng là trong nhà hay ngoài trời. Ví dụ: PhotoSpheres không được trả lại 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
Ảnh chụp màn hình ảnh chụp một địa điểm quan sát ở trên cao đường phố, cho thấy các đường ray xe lửa điện khí hoá.

Không có hình ảnh nào

Đối với các vị trí không có hình ảnh Chế độ xem phố, API tĩnh của Chế độ xem phố trả về hình ảnh chung màu xám kèm theo nội dung "Rất tiếc, chúng tôi không có hình ảnh đây.", như trong ví dụ sau:

Ảnh chụp màn hình của hình ảnh chung xuất hiện khi không có hình ảnh cho vị trí được chỉ định. Nền có màu nâu nhạt và hiển thị văn bản "Xin lỗi, chúng tôi không có hình ảnh ở đây".
Hình: Hình ảnh chung được hiển thị khi không có hình ảnh cho vị trí cụ thể.

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 phố hợp lệ, hãy làm theo đề xuất:

  • Đặt tham số return_error_code thành true. Việc 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 nào cho vị trí đã chỉ định trước đó hay không đến việc gửi yêu cầu.