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

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

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

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

Введение

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

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

Попробуйте!

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

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

Запрос «Поиск поблизости (новый)» — это 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.movedPlace
  places.movedPlaceId
  places.photos
  places.plusCode
  places.postalAddress
  places.primaryType
  places.primaryTypeDisplayName
  places.pureServiceAreaBusiness
  places.shortFormattedAddress
  places.subDestinations
  places.types
  places.utcOffsetMinutes
  places.viewport
  
  ^* Адресные дескрипторы, как правило, доступны для клиентов в Индии и являются экспериментальными в других местах.
  
  ^** Поле 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
  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, разделённых запятыми, для поиска. Если этот параметр пропущен, возвращаются места всех типов.
исключенные типы
Список типов мест из таблицы А, разделенных запятыми, которые следует исключить из поиска.
Если в запросе указаны как includedTypes (например, "school" ), так и excludedTypes (например, "primary_school" ), то ответ будет включать места, относящиеся к категории "school" но не к категории "primary_school" . В ответ будут включены места, соответствующие хотя бы одному из includedTypes и ни одному из excludedTypes .
Если имеются конфликтующие типы, например, тип присутствует и в includedTypes , и excludedTypes , возвращается ошибка INVALID_REQUEST .
включеныPrimaryTypes
Список основных типов мест из таблицы 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» (технически обозначает «Соединённое Королевство Великобритании и Северной Ирландии»). Этот параметр может влиять на результаты в зависимости от применимого законодательства.

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

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

В следующем примере показан запрос «Поиск поблизости (новый)» для отображения названий всех ресторанов в радиусе 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 Places, в которых в маске поля используется только addressDescriptor будут оплачиваться по артикулу: Places API Nearby Search Pro .

В следующем примере показан запрос «Поиск поблизости (новый)» для поиска мест рядом с торговым центром в Сан-Хосе. В этом примере 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

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

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

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

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

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

включеныPrimaryTypes

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

код_языка

maxResultCount

rankPreference

Код региона

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

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

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

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

Поиск всех мест рядом с выбранным районом, ранжирование по расстоянию

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

Попробуйте!

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