Фотографии мест (новинка)

Выберите платформу: Android iOS Web Service

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

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

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

Запросы на размещение фотографий (новых)

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

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

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

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

Требуемые параметры

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

Строковый идентификатор, который уникально идентифицирует фотографию. Названия фотографий возвращаются из запроса Place Details (New) , Nearby Search (New) или Text Search (New) в свойстве name каждого элемента массива photos[] .

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

maxHeightPx и maxWidthPx

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

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

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

пропуститьHttpRedirect

Если 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) должны включать имя фоторесурса, возвращаемое в ответе на запрос Nearby Search (New), Text Search (New) или Place Details (New). Ответ на эти запросы содержит массив photos[] , если место имеет связанный фотографический контент.

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

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

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

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

В следующем примере показан запрос Place Details (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/AUacShh3_Dd8yvV2JZMtNjjbbSbFhSv-0VmUN-uasQ2Oj00XB63irPTks0-A_1rMNfdTunoOVZfVOExRRBNrupUf8TY4Kw5iQNQgf2rwcaM8hXNQg7KDyvMR5B-HzoCE1mwy2ba9yxvmtiJrdV-xBgO8c5iJL65BCd0slyI1/media?maxHeightPx=400&maxWidthPx=400&key=API_KEY

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

Коды ошибок

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

Превышена квота (403)

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

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

Неверный запрос (404)

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

  • Название представленной фотографии указано неверно.
  • В запросе не указаны параметры maxHeightPx и maxWidthPx .
  • Значение параметра maxHeightPx или maxWidthtPx было установлено равным null .
  • name устарело. Если name устарело, сделайте запрос в Place Details (New) , Nearby Search (New) или Text Search (New) для получения нового name .

Слишком много запросов (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.