Сведения о месте (новое)

Введение

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

Существует множество способов получить идентификатор места. Вы можете использовать:

• Текстовый поиск (новая функция) или поиск поблизости (новая функция)
• API геокодирования
• API маршрутов
• API проверки адресов
• Автозаполнение (новое)

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

Запросы на подробную информацию о местах (новые)

Запрос "Подробная информация о месте (новый)" представляет собой HTTP GET-запрос в следующем формате:

https://places.googleapis.com/v1/places/PLACE_ID

Передайте все параметры в качестве параметров URL или в заголовках в составе GET-запроса. Например:

https://places.googleapis.com/v1/places/ChIJj61dQgK6j4AR4GeTYWZsKWw?fields=id,displayName&key=API_KEY

Или в команде curl:

curl -X GET -H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: id,displayName" \
https://places.googleapis.com/v1/places/ChIJj61dQgK6j4AR4GeTYWZsKWw

Подробные сведения о месте (новые) ответы

Функция «Подробная информация о месте» (новая) возвращает в ответ JSON-объект . В ответе содержится:

• Ответ представлен объектом Place . Объект Place содержит подробную информацию о месте.
• Передаваемый в запросе параметр FieldMask определяет список полей, возвращаемых в объекте Place .

Полный JSON-объект имеет следующий вид:

{
  "name": "places/ChIJkR8FdQNB0VQRm64T_lv1g1g",
  "id": "ChIJkR8FdQNB0VQRm64T_lv1g1g",
  "displayName": {
    "text": "Trinidad"
  }
  ...
}

Необходимые параметры

• FieldMask

  Укажите список полей, которые должны быть возвращены в ответе, создав маску полей ответа . Передайте маску полей ответа методу, используя параметр URL $fields или fields , или используя HTTP-заголовок X-Goog-FieldMask . В ответе нет списка возвращаемых полей по умолчанию. Если вы опустите маску полей, метод вернет ошибку.

  Использование маскирования полей — это хорошая практика проектирования, позволяющая избежать запроса ненужных данных, что помогает избежать лишнего времени обработки и дополнительных расходов на выставление счетов.

  Укажите список типов данных мест, разделенных запятыми, которые необходимо вернуть. Например, чтобы получить отображаемое имя и адрес места.

  X-Goog-FieldMask: displayName,formattedAddress

  Используйте * для получения всех полей.

  X-Goog-FieldMask: *

  Укажите одно или несколько из следующих полей:

  • Следующие поля активируют SKU, содержащий только основные идентификаторы сведений о месте :

    attributions
id
moved_place
moved_place_id
name ^*
    photos
    

    ^* Поле name содержит название ресурса места в формате: places/ PLACE_ID . Чтобы получить текстовое название места, запросите поле displayName в Pro SKU.

  • Следующие поля активируют SKU «Основные сведения о месте» :

    addressComponents
addressDescriptor ^*
    adrFormatAddress
formattedAddress
location
plusCode
postalAddress
shortFormattedAddress
types
viewport
    
    ^* Адресные описания, как правило, доступны клиентам в Индии, а в других странах находятся на экспериментальной стадии.
    
    

  • Следующие поля активируют артикул Place Details Pro :

    accessibilityOptions
businessStatus
containingPlaces
displayName
googleMapsLinks
googleMapsUri
iconBackgroundColor
iconMaskBaseUri
primaryType
primaryTypeDisplayName
pureServiceAreaBusiness
subDestinations
timeZone
utcOffsetMinutes
    
    

  • Следующие поля запускают функцию создания корпоративного артикула данных о месте :

    currentOpeningHours
currentSecondaryOpeningHours
internationalPhoneNumber
nationalPhoneNumber
priceLevel
priceRange
rating
regularOpeningHours
regularSecondaryOpeningHours
userRatingCount
websiteUri

  • Следующие поля активируют артикул Place Details Enterprise + Atmosphere :

    allowsDogs
curbsidePickup
delivery
dineIn
editorialSummary
evChargeAmenitySummary
evChargeOptions
fuelOptions
generativeSummary
goodForChildren
goodForGroups
goodForWatchingSports
liveMusic
menuForChildren
neighborhoodSummary
parkingOptions
paymentOptions
outdoorSeating
reservable
restroom
reviews
reviewSummary
routingSummaries ^*
    servesBeer
servesBreakfast
servesBrunch
servesCocktails
servesCoffee
servesDessert
servesDinner
servesLunch
servesVegetarianFood
servesWine
takeout
    
    ^* Только текстовый поиск и поиск поблизости

• placeId

  Текстовый идентификатор, однозначно определяющий местоположение, возвращаемый при текстовом поиске (новый) или поиске поблизости (новый) . Для получения дополнительной информации об идентификаторах мест см. обзор идентификаторов мест .

  Строка places/ PLACE_ID также называется именем ресурса места. В ответе на запрос «Подробная информация о месте» (новая функция), «Поиск поблизости» (новая функция) и «Текстовый поиск» (новая функция) эта строка содержится в поле name ответа. Автономный идентификатор места содержится в поле id ответа.

Дополнительные параметры

• languageCode

  Язык, на котором будут возвращаться результаты.

  • См. список поддерживаемых языков . Google часто обновляет список поддерживаемых языков, поэтому этот список может быть неполным.
  • Если languageCode не указан, API по умолчанию использует en . Если вы укажете недопустимый код языка, API вернет ошибку INVALID_ARGUMENT .
  • API делает все возможное, чтобы предоставить уличный адрес, понятный как пользователю, так и местным жителям. Для достижения этой цели он возвращает уличные адреса на местном языке, при необходимости транслитерированные в письменность, понятную пользователю, с учетом предпочтительного языка. Все остальные адреса возвращаются на предпочтительном языке. Все компоненты адреса возвращаются на одном языке, который выбирается из первого компонента.
  • Если имя недоступно на предпочитаемом языке, API использует наиболее близкое совпадение.
  • Предпочитаемый язык оказывает незначительное влияние на набор результатов, которые API выбирает для возврата, и на порядок их возврата. Геокодер по-разному интерпретирует сокращения в зависимости от языка, например, сокращения для типов улиц или синонимы, которые могут быть допустимы в одном языке, но не в другом.

• regionCode

  Региональный код, используемый для форматирования ответа, указывается в виде двухсимвольного кода CLDR . Значение по умолчанию отсутствует.

  Если название страны в поле formattedAddress в ответе совпадает с regionCode , код страны опускается в formattedAddress . Этот параметр не влияет на adrFormatAddress , который всегда включает название страны, или на shortFormattedAddress , который никогда его не включает.

  Большинство кодов CLDR идентичны кодам ISO 3166-1, за некоторыми заметными исключениями. Например, национальный домен верхнего уровня Соединенного Королевства — «uk» (.co.uk), а его код ISO 3166-1 — «gb» (технически обозначающий «Соединенное Королевство Великобритании и Северной Ирландии»). Параметр может влиять на результаты в зависимости от применимого законодательства.

• sessionToken

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

Пример сведений о месте (новое).

В следующем примере запрашиваются подробные сведения о месте по идентификатору места placeId :

curl -X GET -H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: id,displayName" \
https://places.googleapis.com/v1/places/ChIJj61dQgK6j4AR4GeTYWZsKWw

Обратите внимание, что заголовок X-Goog-FieldMask указывает, что ответ должен содержать следующие поля данных: id,displayName . В этом случае ответ будет иметь следующий вид:

{
  "id": "ChIJj61dQgK6j4AR4GeTYWZsKWw",
  "displayName": {
    "text": "Googleplex",
    "languageCode": "en"
  }
}

Добавьте в маску поля дополнительные типы данных, чтобы получать более полную информацию. Например, добавьте formattedAddress,plusCode чтобы включить адрес и код Plus в ответ :

curl -X GET -H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: id,displayName,formattedAddress,plusCode" \
https://places.googleapis.com/v1/places/ChIJj61dQgK6j4AR4GeTYWZsKWw

Ответ теперь представлен в следующем виде:

{
  "id": "ChIJj61dQgK6j4AR4GeTYWZsKWw",
  "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
  "plusCode": {
    "globalCode": "849VCWC7+RW",
    "compoundCode": "CWC7+RW Mountain View, CA, USA"
  },
  "displayName": {
    "text": "Googleplex",
    "languageCode": "en"
  }
}

Получить описания адресов

Адресные описания предоставляют информацию о местоположении места, включая близлежащие достопримечательности и входящие в него территории.

В следующем примере показан запрос на получение сведений о месте (новый) для универмага в торговом центре Сан-Хосе. В этом примере в маску поля необходимо включить addressDescriptors :

  curl -X GET https://places.googleapis.com/v1/places/ChIJ8WvuSB7Lj4ARFyHppkxDRQ4 \
  -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
  -H "X-Goog-FieldMask: name,displayName,addressDescriptor"

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

  {
    "name": "places/ChIJ8WvuSB7Lj4ARFyHppkxDRQ4",
    "displayName": {
      "text": "Macy's",
      "languageCode": "en"
    },
    "addressDescriptor": {
      "landmarks": [
        {
          "name": "places/ChIJVVVVUB7Lj4ARXyb4HFVDV8s",
          "placeId": "ChIJVVVVUB7Lj4ARXyb4HFVDV8s",
          "displayName": {
            "text": "Westfield Valley Fair",
            "languageCode": "en"
          },
          "types": [
            "clothing_store",
            "department_store",
            "establishment",
            "food",
            "movie_theater",
            "point_of_interest",
            "restaurant",
            "shoe_store",
            "shopping_mall",
            "store"
          ],
          "spatialRelationship": "WITHIN",
          "straightLineDistanceMeters": 220.29175
        },
        {
          "name": "places/ChIJ62_oCR7Lj4AR_MGWkSPotD4",
          "placeId": "ChIJ62_oCR7Lj4AR_MGWkSPotD4",
          "displayName": {
            "text": "Nordstrom",
            "languageCode": "en"
          },
          "types": [
            "clothing_store",
            "department_store",
            "establishment",
            "point_of_interest",
            "shoe_store",
            "store"
          ],
          "straightLineDistanceMeters": 329.45178
        },
        {
          "name": "places/ChIJmx1c5x7Lj4ARJXJy_CU_JbE",
          "placeId": "ChIJmx1c5x7Lj4ARJXJy_CU_JbE",
          "displayName": {
            "text": "Monroe Parking Garage",
            "languageCode": "en"
          },
          "types": [
            "establishment",
            "parking",
            "point_of_interest"
          ],
          "straightLineDistanceMeters": 227.05153
        },
        {
          "name": "places/ChIJxcwBziHLj4ARUQLAvtzkRCM",
          "placeId": "ChIJxcwBziHLj4ARUQLAvtzkRCM",
          "displayName": {
            "text": "Studios Inn by Daiwa Living California Inc.",
            "languageCode": "en"
          },
          "types": [
            "establishment",
            "lodging",
            "point_of_interest",
            "real_estate_agency"
          ],
          "straightLineDistanceMeters": 299.9955
        },
        {
          "name": "places/ChIJWWIlNx7Lj4ARpe1E0ob-_GI",
          "placeId": "ChIJWWIlNx7Lj4ARpe1E0ob-_GI",
          "displayName": {
            "text": "Din Tai Fung",
            "languageCode": "en"
          },
          "types": [
            "establishment",
            "food",
            "point_of_interest",
            "restaurant"
          ],
          "straightLineDistanceMeters": 157.70943
        }
      ],
      "areas": [
        {
          "name": "places/ChIJb3F-EB7Lj4ARnHApQ_Hu1gI",
          "placeId": "ChIJb3F-EB7Lj4ARnHApQ_Hu1gI",
          "displayName": {
            "text": "Westfield Valley Fair",
            "languageCode": "en"
          },
          "containment": "WITHIN"
        },
        {
          "name": "places/ChIJXYuykB_Lj4AR1Ot8nU5q26Q",
          "placeId": "ChIJXYuykB_Lj4AR1Ot8nU5q26Q",
          "displayName": {
            "text": "Valley Fair",
            "languageCode": "en"
          },
          "containment": "WITHIN"
        },
        {
          "name": "places/ChIJtYoUX2DLj4ARKoKOb1G0CpM",
          "placeId": "ChIJtYoUX2DLj4ARKoKOb1G0CpM",
          "displayName": {
            "text": "Central San Jose",
            "languageCode": "en"
          },
          "containment": "WITHIN"
        }
      ]
    }
  }

Получите подробную информацию о месте жительства после переезда.

Если место, на которое ссылается ваше приложение, переехало, вы можете использовать поля movedPlace и movedPlaceId чтобы получить подробную информацию о новом месте.

Для мест, которые закрыты навсегда , функция Place Details (New) возвращает CLOSED_PERMANENTLY в поле businessStatus и пропускает поля movedPlace и movedPlaceId в теле ответа.

Для мест , переехавших на новое место , функция Place Details (New) возвращает значение CLOSED_PERMANENTLY в поле businessStatus и указывает новое местоположение в полях movedPlace и movedPlaceId в теле ответа.

Для мест, которые не были перемещены , функция «Подробная информация о месте (Новое)» не возвращает movedPlace или movedPlaceId в теле ответа.

В следующем примере запрашивается информация о магазине Marche IGA St-Canut в Квебеке, Канада:

curl -X  GET -H 'Content-Type: application/json' \
-H 'x-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: id,displayName,businessStatus,movedPlace,movedPlaceId' \
https://places.googleapis.com/v1/places/ChIJUfQdGInVzkwRzAjmjzWB7CQ

В ответ на запрос возвращается следующая информация:

{
  "id": "ChIJUfQdGInVzkwRzAjmjzWB7CQ",
  "businessStatus": "CLOSED_PERMANENTLY",
  "displayName": {
    "text": "Marche IGA St-Canut",
    "languageCode": "en"
  },
  "movedPlace": "places/ChIJ36QT7n8qz0wRDqVZ_UBlUlQ",
  "movedPlaceId": "ChIJ36QT7n8qz0wRDqVZ_UBlUlQ"
}

Чтобы запросить подробную информацию о новом месте, используйте имя ресурса «Место» в поле movedPlace в новом запросе на получение сведений о новом месте.

Для мест, которые неоднократно меняли местоположение , получение информации о текущем местоположении может потребовать нескольких последовательных запросов Place Details (New). Поля movedPlace и movedPlaceId в результате запроса Place указывают только на следующее известное местоположение, а не на последнее. Место находится в текущем местоположении, если запрос Place Details (New) не содержит полей movedPlace и movedPlaceId в теле ответа.

Попробуйте!

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

1. Выберите значок API в правой части страницы.

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

3. Нажмите кнопку «Выполнить» . В диалоговом окне выберите учетную запись, которую вы хотите использовать для выполнения запроса.

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