Dịch vụ Place Photo (Ảnh địa điểm) là một phần của Places API là API chỉ có thể đọc cho phép bạn thêm nội dung ảnh chất lượng cao vào ứng dụng. Dịch vụ Ảnh địa điểm cho phép bạn truy cập vào hàng triệu ảnh được lưu trữ trong cơ sở dữ liệu Địa điểm. Khi bạn nhận thông tin địa điểm bằng cách sử dụng yêu cầu Chi tiết địa điểm, tham chiếu ảnh sẽ được trả lại cho nội dung ảnh có liên quan. Các yêu cầu Tìm địa điểm, Tìm kiếm lân cận và Tìm kiếm văn bản cũng trả về một tham chiếu ảnh duy nhất cho mỗi địa điểm, khi có liên quan. Khi sử dụng dịch vụ Ảnh, bạn có thể truy cập vào ảnh được tham chiếu và đổi kích thước hình ảnh thành kích thước tối ưu cho ứng dụng của mình.
Yêu cầu chụp ảnh cho địa điểm
Yêu cầu hình ảnh địa điểm là một URL HTTP thuộc biểu mẫu sau:
https://maps.googleapis.com/maps/api/place/photo?parameters
Cần có một số tham số để khởi tạo yêu cầu tìm kiếm. 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à (&
). Danh sách
các tham số và giá trị có thể có được liệt kê dưới đây.
Required parameters
photo_reference
A string identifier that uniquely identifies a photo. Photo references are returned from either a Place Search or Place Details request.
maxheight or maxwidth
maxheight
specifies the maximum desired height, in pixels, of the image. If the image is smaller than the values specified, the original image will be returned. If the image is larger in either dimension, it will be scaled to match the smaller of the two dimensions, restricted to its original aspect ratio.maxwidth
specifies the maximum desired width, in pixels, of the image. If the image is smaller than the values specified, the original image will be returned. If the image is larger in either dimension, it will be scaled to match the smaller of the two dimensions, restricted to its original aspect ratio.Both the
maxheight
andmaxwidth
properties accept an integer between1
and1600
.You must specify either
maxheight
, ormaxwidth
, or both.
Hình ảnh tham khảo
Tất cả yêu cầu gửi đến dịch vụ Ảnh địa điểm phải bao gồm photo_reference
. API này được trả về trong phản hồi cho yêu cầu Tìm địa điểm, Tìm kiếm lân cận, Tìm kiếm văn bản hoặc Chi tiết địa điểm. Phản hồi cho các yêu cầu này sẽ chứa trường photos[]
nếu địa điểm đó có nội dung ảnh liên quan.
Lưu ý: Số lượng ảnh được trả lại sẽ khác nhau tuỳ theo yêu cầu.
- Yêu cầu Tìm địa điểm, Tìm kiếm lân cận hoặc Tìm kiếm văn bản trả về tối đa một phần tử
photo
trong mảng. - Yêu cầu Thông tin chi tiết về địa điểm trả về tối đa 10 phần tử
photo
.
Mỗi phần tử photo
chứa các trường sau:
photo_reference
– một chuỗi dùng để xác định ảnh khi bạn thực hiện yêu cầu Ảnh.height
– chiều cao tối đa của hình ảnh.width
– chiều rộng tối đa của hình ảnh.html_attributions[]
– chứa mọi thuộc tính bắt buộc. Trường này sẽ luôn xuất hiện nhưng có thể trống.
Ảnh do dịch vụ Ảnh trả về được lấy từ nhiều vị trí, bao gồm cả ảnh của chủ doanh nghiệp và ảnh do người dùng đóng góp. Trong hầu hết trường hợp, bạn có thể sử dụng những ảnh này mà không cần ghi nhận tác giả hoặc sẽ có thuộc tính bắt buộc trong hình ảnh. Tuy nhiên, nếu phần tử photo
được trả về có chứa một giá trị trong trường html_attributions
, thì bạn phải đưa thuộc tính bổ sung vào ứng dụng của mình ở bất cứ nơi nào hình ảnh xuất hiện.
Ví dụ sau đây cho thấy yêu cầu Thông tin chi tiết về địa điểm:
curl "https://maps.googleapis.com/maps/api/place/details/json?placeid=ChIJcUElzOzMQQwRLuV30nMUEUM&key=YOUR_API_KEY"
Dưới đây là ví dụ về mảng photos[]
trong phản hồi.
...
"photos" : [
{
"html_attributions" : [],
"height" : 853,
"width" : 1280,
"photo_reference" : "ATJ83zhSSAtkh5LTozXMhBghqubeOxnZWUV2m7Hv2tQaIzKQJgvZk9yCaEjBW0r0Zx1oJ9RF1G7oeM34sQQMOv8s2zA0sgGBiyBgvdyMxeVByRgHUXmv-rkJ2wyvNv17jyTSySm_-_6R2B0v4eKX257HOxvXlx_TSwp2NrICKrZM2d5d2P4q"
}
...
Ví dụ về Ảnh địa điểm
Dưới đây là một ví dụ về yêu cầu. Yêu cầu này sẽ trả về hình ảnh được tham chiếu, đổi kích thước sao cho hình ảnh có chiều rộng tối đa là 400 pixel.
https://maps.googleapis.com/maps/api/place/photo?maxwidth=400&photo_reference=ATJ83zhSSAtkh5LTozXMhBghqubeOxnZWUV2m7Hv2tQaIzKQJgvZk9yCaEjBW0r0Zx1oJ9RF1G7oeM34sQQMOv8s2zA0sgGBiyBgvdyMxeVByRgHUXmv-rkJ2wyvNv17jyTSySm_-_6R2B0v4eKX257HOxvXlx_TSwp2NrICKrZM2d5d2P4q &key=YOUR_API_KEY
Phản hồi về ảnh địa điểm
Phản hồi của một yêu cầu thành công về Ảnh địa điểm sẽ là một hình ảnh. Loại hình ảnh sẽ phụ thuộc vào loại ảnh được gửi ban đầu.
Nếu yêu cầu của bạn vượt quá hạn mức hiện có, máy chủ sẽ trả về trạng thái HTTP 403 và hiển thị hình ảnh bên dưới để cho biết đã vượt quá hạn mức:
Nếu không hiểu được yêu cầu của bạn thì máy chủ sẽ trả về trạng thái HTTP 400 cho biết yêu cầu không hợp lệ. Sau đây là những lý do phổ biến nhất dẫn đến yêu cầu không hợp lệ:
- Ảnh tham chiếu đã gửi không được chỉ định chính xác.
- Yêu cầu không bao gồm tham số
maxwidth
hoặcmaxheight
. - Giá trị cho tham số
maxwidth
hoặcmaxheight
đã được đặt thànhnull
. photo_reference
đã hết hạn. Nếuphoto_reference
hết hạn, hãy đưa ra yêu cầu Thông tin chi tiết về địa điểm, Tìm địa điểm, Tìm kiếm lân cận hoặc Tìm kiếm bằng văn bản để nhận giá trị đã cập nhật củaphoto_reference
.