Place Photos (New)

Выберите платформу: Android iOS Веб-сервисы
Разработчики из Европейской экономической зоны (ЕЭЗ)

Введение

Сервис Place Photos (New) – это API, предназначенный только для чтения, который позволяет добавлять в приложение высококачественные фотографии. Place Photos (Новое) предоставляет доступ к миллионам фотографий, хранящихся в базе данных Places.

При запросе данных о месте с помощью новых функций Place Details, Nearby Search или Text Search вы также можете запросить ресурсы фотографий для соответствующего контента. Используя фотографии мест (новые), вы можете получить доступ к упомянутым фотографиям и изменить размер изображения до оптимального для вашего приложения.

API Explorer позволяет отправлять запросы в реальном времени, чтобы вы могли ознакомиться с API и его возможностями.

Запросы Place Photos (New)

Запрос Place Photos (New) – это HTTP-запрос GET к URL в следующем формате: 
https://places.googleapis.com/v1/NAME/media?key=API_KEY&PARAMETERS

где требуются следующие параметры:

  • NAME содержит название ресурса фотографии.
  • API_KEY содержит ключ API.
  • PARAMETERS содержит параметр maxHeightPx, параметр maxWidthPx или оба этих параметра.

Полный список обязательных и необязательных параметров приведен ниже.

Обязательные параметры

Название фотографии

Строковый идентификатор, который однозначно определяет фотографию. Названия фотографий возвращаются из запроса информация о местах (New), поиск поблизости (New) или текстовый поиск (New) в свойстве name каждого элемента массива photos[].

Пример приведен в разделе Получение названия фотографии.

maxHeightPx и maxWidthPx;

Указывает максимальную высоту и ширину изображения в пикселях. Если изображение меньше указанных значений, будет возвращено исходное изображение. Если изображение больше по какому-либо из параметров, оно будет масштабировано в соответствии с меньшим из двух параметров с сохранением исходного соотношения сторон. Свойства maxheight и maxwidth принимают целое число от 1 до 4800.

Необходимо указать maxHeightPx, maxWidthPx или оба параметра.

Необязательные параметры

skipHttpRedirect

Если false (по умолчанию), выполните HTTP-перенаправление на изображение, чтобы вернуть его. Если true, пропустите перенаправление и верните ответ JSON, содержащий сведения об изображении. Пример:

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

Этот параметр игнорируется для запросов, не относящихся к HTTP.

Как узнать название фотографии

Все запросы к Place Photos (New) должны содержать название ресурса фотографии, возвращенное в ответе на запрос поиска поблизости (New), текстового поиска (New) или информации о местах (New). Ответ на эти запросы содержит массив photos[], если для места есть связанный фотоконтент.

Каждый элемент photo[] содержит следующие поля:

  • name – строка, содержащая название ресурса фотографии, когда вы выполняете запрос к Фото. Строка имеет следующий формат:

    places/PLACE_ID/photos/PHOTO_RESOURCE
  • heightPx – максимальная высота изображения в пикселях.
  • widthPx – максимальная ширина изображения в пикселях.
  • authorAttributions[] – любые необходимые указания авторства. Это поле всегда присутствует, но может быть пустым.

Сервис "Фото мест (новая версия)" передает изображения из множества источников, в том числе фотографии, предоставленные владельцами компаний и пользователями. Как правило, такие фотографии можно использовать без упоминания авторства, или оно будет указано непосредственно на снимке. Однако, если возвращенный элемент photo содержит значение в поле authorAttributions, в приложении вместе с изображением необходимо дополнительно указывать авторство.

В примере ниже показан запрос информации о местах (New), в маску полей которого включено поле photos. Благодаря этому в ответе будет массив photos[].

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
 Ниже приведен пример массива photos[] в ответе. 
    ...
    "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"
          }
        ]
      },
    ...

Как запросить фотографию места

В примере запроса ниже возвращается изображение с использованием ресурса name, размер которого изменяется так, чтобы его высота и ширина не превышали 400 пикселей:

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

Ответом на успешный запрос Place Photos (New) является изображение.

Коды ошибок

Запросы Place Photos (New) могут возвращать следующие коды ошибок.

Квота превышена (403)

Если запрос превышает доступную квоту, сервер возвращает статус HTTP 403 и показывает следующее изображение, указывающее на превышение квоты:

Уведомление о превышении квоты

Недействительный запрос (404)

Если сервер не может обработать ваш запрос, он возвращает статус HTTP 400, который указывает на недопустимый запрос. Наиболее распространенные причины недействительного запроса:

Слишком много запросов (429)

Google рекомендует загружать фотографии по запросу. Если вы попытаетесь показать все изображения места одновременно, сервер может вернуть статус HTTP 429, указывающий на одновременную загрузку слишком большого количества фотографий. Если вы получили такое сообщение об ошибке, обратитесь в службу поддержки и запросите увеличение квоты.

Попробовать

API Explorer позволяет отправлять примеры запросов, чтобы вы могли ознакомиться с API и его возможностями.

Чтобы отправить запрос:

  1. Нажмите на значок API в правой части страницы.
  2. Задайте для параметра name следующее значение: 
    places/PLACE_ID/photos/PHOTO_RESOURCE/media
  3. Установите для параметра skipHttpRedirect значение true, чтобы в ответе на запрос был JSON-файл. По умолчанию запрос возвращает изображение, которое не может быть показано в API Explorer.
  4. Нажмите кнопку Выполнить. В диалоговом окне выберите аккаунт, который хотите использовать для запроса.

  5. На панели API Explorer нажмите на значок полноэкранного режима , чтобы развернуть окно API Explorer.