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

Введение

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

Получая информацию о месте с помощью запросов «Информация о месте (новое)», «Поиск поблизости (новое)» или «Текстовый поиск (новое)», вы также можете запросить фоторесурсы для соответствующего фотоконтента. Используя «Фотографии места (новое)», вы можете получить доступ к указанным фотографиям и изменить размер изображения до оптимального для вашего приложения.

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

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

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 , либо оба.

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

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-запросов.

Получить имя фотографии

Все запросы к функциям «Фотографии места (новые)» должны включать название фоторесурса, возвращаемое в ответе на запросы «Поиск рядом (новые)», «Текстовый поиск (новые)» или «Информация о месте (новые)». Ответ на эти запросы содержит массив photos[] если у места есть связанный фотоконтент.

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

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

  places/PLACE_ID/photos/PHOTO_RESOURCE

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

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

В следующем примере показан запрос «Сведения о месте (новый)», который включает 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" : [
      {
        "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) является изображение.

Коды ошибок

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

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

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

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

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

• Название представленной фотографии указано неверно.
• В запросе не указаны параметры maxHeightPx и maxWidthPx .
• Значение параметра maxHeightPx или maxWidthtPx было установлено равным null .
• Срок действия name истек. Если срок действия name истек, отправьте запрос в раздел «Информация о месте (новое)» , «Поиск рядом (новое)» или «Текстовый поиск (новое)», чтобы получить новое name .

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

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

Попробуйте!

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

Чтобы сделать запрос:

1. Выберите значок API api на правой стороне страницы.
2. Задайте параметру name следующее значение:

   places/PLACE_ID/photos/PHOTO_RESOURCE/media

3. Установите skipHttpRedirect в true , чтобы запрос возвращал ответ в формате JSON. По умолчанию запрос возвращает изображение, которое не может быть отображено в API Explorer.
4. Нажмите кнопку «Выполнить» . В диалоговом окне выберите учётную запись, которую вы хотите использовать для отправки запроса.

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