Ảnh địa điểm (Mới)

Chọn nền tảng: Android iOS Dịch vụ web
Nhà phát triển ở Khu vực kinh tế Châu Âu (EEA)

Giới thiệu

Dịch vụ Ảnh địa điểm (Mới) là một API chỉ đọc, cho phép bạn thêm nội dung ảnh chất lượng cao vào ứng dụng của mình. Place Photos (Mới) cho phép bạn truy cập vào hàng triệu bức ảnh được lưu trữ trong cơ sở dữ liệu Places.

Khi nhận thông tin về địa điểm bằng yêu cầu Place Details (New), Nearby Search (New) hoặc Text Search (New), bạn cũng có thể yêu cầu tài nguyên ảnh cho nội dung nhiếp ảnh có liên quan. Khi dùng Place Photos (Mới), bạn có thể truy cập vào các bức ả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.

API Explorer cho phép bạn đưa ra các yêu cầu trực tiếp để có thể làm quen với API và các lựa chọn API:

Yêu cầu về Hình ảnh về địa điểm (Mới)

Yêu cầu Place Photos (Mới) là một yêu cầu HTTP GET đến một URL có dạng: 
https://places.googleapis.com/v1/NAME/media?key=API_KEY&PARAMETERS

Trong đó, các tham số sau đây là bắt buộc:

  • NAME chứa tên tài nguyên của bức ảnh.
  • API_KEY chứa khoá API.
  • PARAMETERS chứa tham số maxHeightPx, tham số maxWidthPx hoặc cả hai.

Danh sách đầy đủ các tham số bắt buộc và không bắt buộc được mô tả dưới đây.

Thông số bắt buộc

Tên ảnh

Giá trị nhận dạng chuỗi xác định riêng biệt một bức ảnh. Tên ảnh được trả về từ yêu cầu Chi tiết về địa điểm (Mới), Tìm kiếm lân cận (Mới) hoặc Tìm kiếm bằng văn bản (Mới) trong thuộc tính name của từng phần tử trong mảng photos[].

Để biết ví dụ, hãy xem phần Lấy tên ảnh.

maxHeightPx và maxWidthPx

Chỉ định chiều cao và chiều rộng tối đa dự kiến của hình ảnh, tính bằng pixel. Nếu hình ảnh nhỏ hơn các giá trị được chỉ định, hình ảnh gốc sẽ được trả về. Nếu hình ảnh lớn hơn ở một trong hai chiều, thì hình ảnh đó sẽ được điều chỉnh tỷ lệ cho phù hợp với chiều nhỏ hơn trong hai chiều, bị hạn chế theo tỷ lệ khung hình ban đầu. Cả thuộc tính maxheight và maxwidth đều chấp nhận một số nguyên từ 1 đến 4800.

Bạn phải chỉ định maxHeightPx hoặc maxWidthPx hoặc cả hai.

Thông số tùy chọn

skipHttpRedirect

Nếu false (mặc định), hãy thực hiện lệnh chuyển hướng HTTP đến hình ảnh để trả về hình ảnh. Nếu true, hãy bỏ qua lệnh chuyển hướng và trả về một phản hồi JSON chứa thông tin chi tiết về hình ảnh. Ví dụ:

{
  "name": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw/photos/Aaw_FcKly0DEv3EWmDJyHiEqXIP5mowOc99lN1GzBun6KHH52AZ5fFA/media",
  "photoUri": "https://lh3.googleusercontent.com/a-/AD_cFT-b=s100-p-k-no-mo"
}

Tuỳ chọn này sẽ bị bỏ qua đối với các yêu cầu không phải là HTTP.

Lấy tên ảnh

Tất cả các yêu cầu đối với Place Photos (Mới) đều phải có tên tài nguyên ảnh, được trả về trong phản hồi cho yêu cầu Nearby Search (Mới), Text Search (Mới) hoặc Place Details (Mới). Phản hồi cho các yêu cầu này chứa một mảng photos[] nếu địa điểm có nội dung ảnh liên quan.

Mỗi phần tử của photo[] chứa các trường sau:

  • name – Một chuỗi chứa tên tài nguyên của bức ảnh khi bạn thực hiện yêu cầu về ảnh. Chuỗi này có dạng:

    places/PLACE_ID/photos/PHOTO_RESOURCE
  • heightPx – Chiều cao tối đa của hình ảnh, tính bằng pixel.
  • widthPx – Chiều rộng tối đa của hình ảnh, tính bằng pixel.
  • authorAttributions[] – Mọi thông tin ghi công bắt buộc. Trường này luôn xuất hiện nhưng có thể trống.

Ảnh do Place Photos (Mới) trả về được lấy từ nhiều vị trí, bao gồm cả ảnh do chủ sở hữu doanh nghiệp và 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 bức ảnh này mà không cần ghi nhận quyền tác giả hoặc sẽ có thông tin ghi nhận quyền tác giả 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 authorAttributions, thì bạn phải thêm thông tin ghi công bổ sung vào ứng dụng của mình bất cứ khi nào bạn hiển thị hình ảnh.

Ví dụ sau đây cho thấy một yêu cầu Chi tiết về địa điểm (Mới) bao gồm photos trong mặt nạ trường để phản hồi bao gồm mảng photos[] trong phản hồi:

curl -X GET \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: id,displayName,photos" \
https://places.googleapis.com/v1/places/ChIJ2fzCmcW7j4AR2JzfXBBoh6E
 Dưới đây là ví dụ về một mảng photos[] trong phản hồi. 
    ...
    "photos" : [
      {
        "name": "places/ChIJ2fzCmcW7j4AR2JzfXBBoh6E/photos/AUacShh3_Dd8yvV2JZMtNjjbbSbFhSv-0VmUN-uasQ2Oj00XB63irPTks0-A_1rMNfdTunoOVZfVOExRRBNrupUf8TY4Kw5iQNQgf2rwcaM8hXNQg7KDyvMR5B-HzoCE1mwy2ba9yxvmtiJrdV-xBgO8c5iJL65BCd0slyI1",
        "widthPx": 6000,
        "heightPx": 4000,
        "authorAttributions": [
          {
            "displayName": "John Smith",
            "uri": "//maps.google.com/maps/contrib/101563",
            "photoUri": "//lh3.googleusercontent.com/a-/AD_cFT-b=s100-p-k-no-mo"
          }
        ]
      },
    ...

Yêu cầu chụp ảnh về một địa điểm

Yêu cầu ví dụ bên dưới trả về một hình ảnh bằng cách sử dụng name tài nguyên của hình ảnh đó, thay đổi kích thước để hình ảnh có chiều cao và chiều rộng tối đa là 400 pixel:

https://places.googleapis.com/v1/places/ChIJ2fzCmcW7j4AR2JzfXBBoh6E/photos/ATKogpeivkIjQ1FT7QmbeT33nBSwqLhdPvIWHfrG1WfmgrFjeZYpS_Ls7c7rj8jejN9QGzlx4GoAH0atSvUzATDrgrZic_tTEJdeITdWL-oG3TWi5HqZoLozrjTaxoAIxmROHfV5KXVcLeTdCC6kmZExSy0CLVIG3lAPIgmvUiewNf-ZHYE4-jXYwPQpWHJgqVosvZJ6KWEgowEA-qRAzNTu9VH6BPFqHakGQ7EqBAeYOiU8Dh-xIQC8FcBJiTi0xB4tr-MYXUaF0p_AqzAhJcDE6FAgLqG1s7EsME0o36w2nDRHA-IuoISBC3SIahINE3Xwq2FzEZE6TpNTFVfgTpdPhV8CGLeqrauHn2I6ePm-2hA8-87aO7aClXKJJVzlQ1dc_JuHz6Ks07d2gglw-ZQ3ibCTF5lMtCF9O-9JHyRQXsfuXw/media?maxHeightPx=400&maxWidthPx=400&key=API_KEY

Phản hồi của một yêu cầu thành công về Place Photos (Mới) là một hình ảnh.

Mã lỗi

Các yêu cầu về Ảnh địa điểm (Mới) có thể trả về các mã lỗi sau.

Đã vượt quá hạn mức (403)

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 sau đây để cho biết rằng hạn mức đã bị vượt quá:

Thông báo vượt quá hạn mức

Yêu cầu không hợp lệ (404)

Nếu không hiểu được yêu cầu của bạn, 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 khiến yêu cầu không hợp lệ:

  • Bạn đã chỉ định tên ảnh được gửi không chính xác.
  • Yêu cầu không bao gồm tham số maxHeightPx hoặc maxWidthPx.
  • Giá trị của tham số maxHeightPx hoặc maxWidthtPx được đặt thành null.
  • Mã name đã hết hạn. Nếu name hết hạn, hãy gửi yêu cầu đến Place Details (New) (Chi tiết về địa điểm (Mới)), Nearby Search (New) (Tìm kiếm lân cận (Mới)) hoặc Text Search (New) (Tìm kiếm bằng văn bản (Mới)) để lấy name mới.

Quá nhiều yêu cầu (429)

Google đề xuất tải ảnh theo yêu cầu. Nếu bạn cố gắng hiển thị tất cả hình ảnh cho một địa điểm cùng một lúc, thì máy chủ có thể trả về trạng thái HTTP 429 cho biết bạn đang tải quá nhiều ảnh cùng một lúc. Nếu bạn nhận được thông báo lỗi này, hãy liên hệ với Nhóm hỗ trợ và yêu cầu tăng hạn mức.

Hãy dùng thử!

API Explorer cho phép bạn đưa ra các yêu cầu mẫu để làm quen với API và các lựa chọn API.

Cách gửi yêu cầu:

  1. Chọn biểu tượng API ở bên phải trang.
  2. Đặt tham số name thành: 
    places/PLACE_ID/photos/PHOTO_RESOURCE/media
  3. Đặt skipHttpRedirect thành true để yêu cầu trả về một phản hồi JSON. Theo mặc định, yêu cầu sẽ trả về hình ảnh mà Trình khám phá API không thể hiển thị.
  4. Chọn nút Thực thi. Trong hộp thoại, hãy chọn tài khoản mà bạn muốn dùng để đưa ra yêu cầu.

  5. Trong bảng điều khiển API Explorer, hãy chọn biểu tượng toàn màn hình để mở rộng cửa sổ API Explorer.