Эта страница переведена с помощью Cloud Translation API.

Поиск поблизости (новинка)

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

Разработчики Европейской экономической зоны (ЕЭЗ)

Введение

Запрос Nearby Search (New) принимает один или несколько типов мест и возвращает список соответствующих мест в указанной области. Требуется маска поля, указывающая один или несколько типов данных. Nearby Search (New) поддерживает только запросы POST.

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

Попробуйте!

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

Запросы на поиск поблизости (новые)

Запрос Nearby Search (New) представляет собой HTTP-запрос POST к URL-адресу в форме:

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

Передайте все параметры в теле запроса JSON или в заголовках как часть запроса POST. Например:

curl -X POST -d '{
  "includedTypes": ["restaurant"],
  "maxResultCount": 10,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965},
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName" \
https://places.googleapis.com/v1/places:searchNearby

Ответы на поиск поблизости (новые)

Nearby Search (New) возвращает объект JSON в качестве ответа . В ответе:

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

Полный объект JSON имеет вид:

{
  "places": [
    {
      object (Place)
    }
  ]
}

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

FieldMask
Укажите список полей для возврата в ответе, создав маску поля ответа . Передайте маску поля ответа в метод, используя параметр URL $fields или fields или используя заголовок HTTP X-Goog-FieldMask . В ответе нет списка возвращаемых полей по умолчанию. Если опустить маску поля, метод вернет ошибку.
Маскировка полей — это хорошая практика проектирования, которая позволяет избежать запроса ненужных данных, что помогает избежать ненужного времени обработки и расходов на выставление счетов.
Укажите разделенный запятыми список типов данных мест для возврата. Например, чтобы получить отображаемое имя и адрес места.
```
X-Goog-FieldMask: places.displayName,places.formattedAddress
```
Примечание: пробелы не допускаются нигде в списке полей.
Используйте * для извлечения всех полей.
```
X-Goog-FieldMask: *
```
Подстановочный знак "*" выбирает все поля. Однако, хотя этот подстановочный знак можно использовать при разработке, Google не рекомендует использовать подстановочный знак (*) в качестве маски поля ответа в производстве из-за большого объема данных, которые могут быть возвращены.
Дополнительные инструкции по использованию places.iconMaskBaseUri и places.iconBackgroundColor можно найти в разделе Значки мест .
Укажите одно или несколько из следующих полей:
- Следующие поля активируют Nearby Search Pro SKU :
  places.accessibilityOptions
  places.addressComponents
  places.addressDescriptor ^*
  places.adrFormatAddress
  places.attributions
  places.businessStatus
  places.containingPlaces
  places.displayName
  places.formattedAddress
  places.googleMapsLinks ^**
  places.googleMapsUri
  places.iconBackgroundColor
  places.iconMaskBaseUri
  places.id
  places.location
  places.name ^***
  places.photos
  places.plusCode
  places.postalAddress
  places.primaryType
  places.primaryTypeDisplayName
  places.pureServiceAreaBusiness
  places.shortFormattedAddress
  places.subDestinations
  places.types
  places.utcOffsetMinutes
  places.viewport
  
  ^* Адресные дескрипторы, как правило, доступны для клиентов в Индии и являются экспериментальными в других местах.
  
  ^** Поле places.googleMapsLinks находится на этапе предварительной версии GA, и плата за его использование в период предварительной версии не взимается (то есть плата составляет 0 долл. США).
  
  ^*** Поле places.name содержит имя ресурса места в форме: places/ PLACE_ID . Используйте places.displayName для доступа к текстовому имени места.
- Следующие поля активируют Nearby Search Enterprise SKU :
  places.currentOpeningHours
  places.currentSecondaryOpeningHours
  places.internationalPhoneNumber
  places.nationalPhoneNumber
  places.priceLevel
  places.priceRange
  places.rating
  places.regularOpeningHours
  places.regularSecondaryOpeningHours
  places.userRatingCount
  places.websiteUri
- Следующие поля активируют Nearby Search Enterprise + Atmosphere SKU :
  places.allowsDogs
  places.curbsidePickup
  places.delivery
  places.dineIn
  places.editorialSummary
  places.evChargeAmenitySummary
  places.evChargeOptions
  places.fuelOptions
  places.generativeSummary
  places.goodForChildren
  places.goodForGroups
  places.goodForWatchingSports
  places.liveMusic
  places.menuForChildren
  places.neighborhoodSummary
  places.parkingOptions
  places.paymentOptions
  places.outdoorSeating
  places.reservable
  places.restroom
  places.reviews
  places.reviewSummary
  places.routingSummaries ^*
  places.servesBeer
  places.servesBreakfast
  places.servesBrunch
  places.servesCocktails
  places.servesCoffee
  places.servesDessert
  places.servesDinner
  places.servesLunch
  places.servesVegetarianFood
  places.servesWine
  places.takeout
  
  ^* Только текстовый поиск и поиск поблизости
местоположениеОграничение
Область поиска, заданная как круг, определяемая центральной точкой и радиусом в метрах. Радиус должен быть между 0,0 и 50000,0 включительно. Радиус по умолчанию равен 0,0. Вы должны установить его в своем запросе на значение больше 0,0.
Например:
```
"locationRestriction": {
  "circle": {
    "center": {
      "latitude": 37.7937,
      "longitude": -122.3965
    },
    "radius": 500.0
  }
}
```

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

включенныеТипы/исключенныеТипы, включенныеПервичныеТипы/исключенныеПервичныеТипы
Позволяет указать список типов из таблицы типов A, используемых для фильтрации результатов поиска. В каждой категории ограничений типов можно указать до 50 типов.
Примечание: Значения в Таблице B возвращаются только в ответе. Вы не можете использовать значения в Таблице B в качестве фильтра.
Место может иметь только один основной тип из типов, связанных с ним в Таблице A. Например, основным типом может быть "mexican_restaurant" или "steak_house" . Используйте includedPrimaryTypes и excludedPrimaryTypes для фильтрации результатов по основному типу места.
Место также может иметь несколько значений типа из типов таблицы A , связанных с ним. Например, ресторан может иметь следующие типы: "seafood_restaurant" , "restaurant" , "food" , "point_of_interest" , "establishment" . Используйте includedTypes и excludedTypes для фильтрации результатов по списку типов, связанных с местом.
Когда вы указываете общий первичный тип, такой как "restaurant" или "hotel" , ответ может содержать места с более конкретным первичным типом, чем указанный. Например, вы указываете включить первичный тип "restaurant" . Затем ответ может содержать места с первичным типом "restaurant" , но ответ также может содержать места с более конкретным первичным типом, таким как "chinese_restaurant" или "seafood_restaurant" .
Если поиск указан с несколькими ограничениями типа, возвращаются только места, которые удовлетворяют всем ограничениям. Например, если указать {"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]} , возвращаемые места предоставляют услуги, связанные с "restaurant" , но не работают в первую очередь как "steak_house" .
Если вы исключите includedTypes , excludedTypes , includedPrimaryTypes и excludedPrimaryTypes из запроса, поиск вернет места для всех типов в пределах границ ограничения местоположения.
включеныТипы
Список типов мест из Таблицы A, разделенных запятыми, для поиска. Если этот параметр пропущен, возвращаются места всех типов.
исключенныеТипы
Список типов мест из таблицы A , разделенных запятыми, которые следует исключить из поиска.
Если вы укажете в запросе как includedTypes (например, "school" ), так и excludedTypes (например, "primary_school" ), то ответ будет включать места, которые относятся к категории "school" , но не "primary_school" . Ответ будет включать места, которые соответствуют хотя бы одному из includedTypes и ни одному из excludedTypes .
Если имеются конфликтующие типы, например, тип присутствует как в includedTypes , так и excludedTypes , возвращается ошибка INVALID_REQUEST .
включеныОсновные типы
Список основных типов мест из таблицы A, разделенных запятыми, для включения в поиск.
исключенныеОсновныеТипы
Список основных типов мест из таблицы A, разделенных запятыми, для исключения из поиска.
Если имеются конфликтующие первичные типы, например, тип присутствует как в includedPrimaryTypes , так и excludedPrimaryTypes , возвращается ошибка INVALID_ARGUMENT .
код языка
Язык, на котором следует возвращать результаты.
- См. список поддерживаемых языков . Google часто обновляет список поддерживаемых языков, поэтому этот список может быть неполным.
- Если languageCode не указан, API по умолчанию использует en . Если указать недопустимый код языка, API возвращает ошибку INVALID_ARGUMENT .
- API делает все возможное, чтобы предоставить адрес, который будет понятен как пользователю, так и местным жителям. Для достижения этой цели он возвращает адрес на местном языке, транслитерированный в сценарий, понятный пользователю, если необходимо, с учетом предпочтительного языка. Все остальные адреса возвращаются на предпочтительном языке. Все компоненты адреса возвращаются на том же языке, который выбирается из первого компонента.
- Если имя недоступно на предпочитаемом языке, API использует наиболее близкое соответствие.
- Предпочтительный язык имеет небольшое влияние на набор результатов, которые API выбирает для возврата, и порядок, в котором они возвращаются. Геокодер интерпретирует сокращения по-разному в зависимости от языка, например, сокращения для типов улиц или синонимы, которые могут быть действительными в одном языке, но не в другом.
maxResultCount
Указывает максимальное количество возвращаемых результатов мест. Должно быть от 1 до 20 (по умолчанию) включительно.
rankPreference
Тип используемого ранжирования. Если этот параметр пропущен, результаты ранжируются по популярности. Может быть одним из следующих:
- POPULARITY (по умолчанию) Сортирует результаты по популярности.
- DISTANCE Сортирует результаты в порядке возрастания расстояния от указанного местоположения.
Код региона
Код региона, используемый для форматирования ответа, указанный как двухсимвольное значение кода CLDR . Значения по умолчанию нет.
Если название страны поля formattedAddress в ответе совпадает с regionCode , код страны исключается из formattedAddress . Этот параметр не влияет на adrFormatAddress , который всегда включает название страны, или на shortFormattedAddress , который никогда его не включает.
Большинство кодов CLDR идентичны кодам ISO 3166-1, за некоторыми заметными исключениями. Например, ccTLD Соединенного Королевства — «uk» (.co.uk), а его код ISO 3166-1 — «gb» (технически для субъекта «Соединенное Королевство Великобритании и Северной Ирландии»). Параметр может влиять на результаты в зависимости от применимого законодательства.

Примеры поиска поблизости (новые)

Найти места одного типа

В следующем примере показан запрос Nearby Search (New) для отображения названий всех ресторанов в радиусе 500 метров, обозначенном circle :

curl -X POST -d '{
  "includedTypes": ["restaurant"],
  "maxResultCount": 10,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965},
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName" \
https://places.googleapis.com/v1/places:searchNearby

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

{
  "places": [
    {
      "displayName": {
        "text": "La Mar Cocina Peruana",
        "languageCode": "en"
      }
    },
    {
      "displayName": {
        "text": "Kokkari Estiatorio",
        "languageCode": "en"
      }
    },
    {
      "displayName": {
        "text": "Harborview Restaurant & Bar",
        "languageCode": "en"
      }
    },
...
}

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

curl -X POST -d '{
  "includedTypes": ["restaurant"],
  "maxResultCount": 10,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965},
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName,places.formattedAddress,places.types,places.websiteUri" \
https://places.googleapis.com/v1/places:searchNearby

Ответ теперь имеет вид:

{
  "places": [
    {
      "types": [
        "seafood_restaurant",
        "restaurant",
        "food",
        "point_of_interest",
        "establishment"
      ],
      "formattedAddress": "PIER 1 1/2 The Embarcadero N, San Francisco, CA 94105, USA",
      "websiteUri": "http://lamarsf.com/",
      "displayName": {
        "text": "La Mar Cocina Peruana",
        "languageCode": "en"
      }
    },
    {
      "types": [
        "greek_restaurant",
        "meal_takeaway",
        "restaurant",
        "food",
        "point_of_interest",
        "establishment"
      ],
      "formattedAddress": "200 Jackson St, San Francisco, CA 94111, USA",
      "websiteUri": "https://kokkari.com/",
      "displayName": {
        "text": "Kokkari Estiatorio",
        "languageCode": "en"
      }
    },
...
}

Найти места разных типов

В следующем примере показан запрос «Поиск поблизости (новый)» для отображения названий всех магазинов у дома и винных магазинов в радиусе 1000 метров от указанного circle :

curl -X POST -d '{
  "includedTypes": ["liquor_store", "convenience_store"],
  "maxResultCount": 10,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965
      },
      "radius": 1000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName,places.primaryType,places.types" \
https://places.googleapis.com/v1/places:searchNearby

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

Исключить тип места из поиска

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

curl -X POST -d '{
  "includedTypes": ["school"],
  "excludedTypes": ["primary_school"],
  "maxResultCount": 10,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965
      },
      "radius": 1000.0
    }
  },
  "rankPreference": "DISTANCE"
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName" \
https://places.googleapis.com/v1/places:searchNearby

Поиск всех мест поблизости от области, ранжирование по расстоянию

В следующем примере показан запрос Nearby Search (New) для мест рядом с точкой в центре Сан-Франциско. В этом примере вы включаете параметр rankPreference для ранжирования результатов по расстоянию:

curl -X POST -d '{
  "maxResultCount": 10,
  "rankPreference": "DISTANCE",
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965
      },
      "radius": 1000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName" \
https://places.googleapis.com/v1/places:searchNearby

Получить дескрипторы адреса

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

Примечание: дескрипторы адресов обычно доступны для клиентов в Индии и являются экспериментальными в других местах. Запросы API мест, которые используют только addressDescriptor в маске поля, будут выставлены по счету SKU: Places API Nearby Search Pro .

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

curl -X POST -d '{
  "maxResultCount": 5,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.321328,
        "longitude": -121.946275
      },"radius": 1000
    }
  },
  "includedTypes": ["restaurant", "cafe"],
  "excludedTypes": [],
  "rankPreference":"POPULARITY"
}' \
-H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName,places.addressDescriptor" \
https://places.googleapis.com/v1/places:searchNearby

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

  {
    "places": [
      {
        "displayName": {
          "text": "Westfield Valley Fair",
          "languageCode": "en"
        },
        "addressDescriptor": {
          "landmarks": [
            {
              "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": 114.76984,
              "travelDistanceMeters": 114.261856
            },
            {
              "name": "places/ChIJgexMlR_Lj4ARiKCKuhNnjn0",
              "placeId": "ChIJgexMlR_Lj4ARiKCKuhNnjn0",
              "displayName": {
                "text": "Valley Fair Mall Eyexam of CA",
                "languageCode": "en"
              },
              "types": [
                "establishment",
                "health",
                "point_of_interest"
              ],
              "straightLineDistanceMeters": 131.62566,
              "travelDistanceMeters": 237.33253
            },
            {
              "name": "places/ChIJWWIlNx7Lj4ARpe1E0ob-_GI",
              "placeId": "ChIJWWIlNx7Lj4ARpe1E0ob-_GI",
              "displayName": {
                "text": "Din Tai Fung",
                "languageCode": "en"
              },
              "types": [
                "establishment",
                "food",
                "point_of_interest",
                "restaurant"
              ],
              "straightLineDistanceMeters": 110.0775,
              "travelDistanceMeters": 171.41951
            },
            {
              "name": "places/ChIJwyfPQx7Lj4AR7bYI2A2Yc54",
              "placeId": "ChIJwyfPQx7Lj4AR7bYI2A2Yc54",
              "displayName": {
                "text": "Abercrombie & Fitch",
                "languageCode": "en"
              },
              "types": [
                "clothing_store",
                "establishment",
                "point_of_interest",
                "shoe_store",
                "store"
              ],
              "spatialRelationship": "DOWN_THE_ROAD",
              "straightLineDistanceMeters": 53.620117,
              "travelDistanceMeters": 2.4578214
            },
            {
              "name": "places/ChIJpycNQx7Lj4ARjhXw3PrM_kU",
              "placeId": "ChIJpycNQx7Lj4ARjhXw3PrM_kU",
              "displayName": {
                "text": "Hollister Co.",
                "languageCode": "en"
              },
              "types": [
                "clothing_store",
                "establishment",
                "point_of_interest",
                "shoe_store",
                "store"
              ],
              "spatialRelationship": "DOWN_THE_ROAD",
              "straightLineDistanceMeters": 56.53726,
              "travelDistanceMeters": 15.418246
            }
          ],
          "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": "OUTSKIRTS"
            }
          ]
        }
      },
  /.../
  }

Попробуйте!

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

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

Поиск поблизости (новинка)

Введение

Запросы на поиск поблизости (новые)

Ответы на поиск поблизости (новые)

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

FieldMask

местоположениеОграничение

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

включенныеТипы/исключенныеТипы, включенныеПервичныеТипы/исключенныеПервичныеТипы

включеныТипы

исключенныеТипы

включеныОсновные типы

исключенныеОсновныеТипы

код языка

maxResultCount

rankPreference

Код региона

Примеры поиска поблизости (новые)

Найти места одного типа

Найти места разных типов

Исключить тип места из поиска

Поиск всех мест поблизости от области, ранжирование по расстоянию

Получить дескрипторы адреса

Попробуйте!