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

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

  2. 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 đến 360 (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 đến location đượ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.


    Ảnh chụp màn hình một trường nhìn trong phạm vi rộng, cho thấy trần nhà, tường, sàn nhà và cửa sổ bể cá bên trong bể cá. Ảnh chụp màn hình trường nhìn cận cảnh, cho thấy chi tiết phóng to của ả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 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à truefalse. Nếu bạn đặt thành true, 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
Ảnh chụp màn hình một ảnh chụp điểm ngắm cảnh ở cấp đường phố, cho thấy tuyến đường sắt được tăng điện.

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:

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

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ành true. Đ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.