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

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

Выберите платформу: Android iOS Веб-служба JavaScript

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

API Explorer позволяет вам делать запросы в реальном времени, чтобы вы могли ознакомиться с API и опциями 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

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

Поиск поблизости (новый) возвращает в качестве ответа объект JSON . В ответ:

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

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

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

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

Маска поля
Укажите список полей, которые будут возвращены в ответе, создав маску поля ответа . Передайте маску поля ответа методу, используя параметр URL $fields или fields или HTTP-заголовок X-Goog-FieldMask . В ответе нет списка возвращаемых полей по умолчанию. Если вы опустите маску поля, метод вернет ошибку.
Маскирование полей — это хорошая практика проектирования, позволяющая избежать запроса ненужных данных, что помогает избежать ненужного времени обработки и затрат на выставление счетов.
Укажите разделенный запятыми список типов данных о местах, которые необходимо вернуть. Например, чтобы получить отображаемое имя и адрес места.
```
X-Goog-FieldMask: places.displayName,places.formattedAddress
```
Примечание. Пробелы в списке полей не допускаются.
Используйте * , чтобы получить все поля.
```
X-Goog-FieldMask: *
```
Подстановочный знак «*» выбирает все поля. Однако, хотя этот подстановочный знак можно использовать в разработке, Google не рекомендует использовать маску поля ответа с подстановочным знаком (*) в рабочей среде из-за большого объема возвращаемых данных.
Дальнейшие инструкции по использованию places.iconMaskBaseUri и places.iconBackgroundColor можно найти в разделе «Значки мест» .
Укажите одно или несколько из следующих полей:
- Следующие поля активируют SKU «Поиск поблизости (базовый)» :
  places.accessibilityOptions , places.addressComponents , 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.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 для доступа к текстовому названию места.
- Следующие поля активируют SKU «Поиск поблизости (расширенный)» :
  places.currentOpeningHours , places.currentSecondaryOpeningHours , places.internationalPhoneNumber , places.nationalPhoneNumber , places.priceLevel , places.priceRange , places.rating , places.regularOpeningHours , places.regularSecondaryOpeningHours , places.userRatingCount , places.websiteUri
- Следующие поля активируют SKU «Поиск поблизости (предпочтительный)» :
  places.allowsDogs , places.curbsidePickup , places.delivery , places.dineIn , places.editorialSummary , places.evChargeOptions , places.fuelOptions , places.goodForChildren , places.goodForGroups , places.goodForWatchingSports , places.liveMusic , places.menuForChildren , places.parkingOptions , places.paymentOptions , places.outdoorSeating , places.reservable , places.restroom , places.reviews , places.routingSummaries , ^* places.servesBeer , places.servesBreakfast places.servesDessert places.servesBrunch , places.servesCocktails , places.servesCoffee , 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
  }
}
```

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

includeTypes/excludedTypes, includePrimaryTypes/excludedPrimaryTypes
Позволяет указать список типов из таблицы типов A, используемых для фильтрации результатов поиска. В каждой категории ограничения типов можно указать до 50 типов.
Примечание. Значения в таблице B возвращаются только в ответе. Значения из таблицы B нельзя использовать в качестве фильтра.
Место может иметь только один основной тип из таблицы типов, связанных с ним. Например, основным типом может быть "mexican_restaurant" или "steak_house" . Используйте includedPrimaryTypes и excludedPrimaryTypes чтобы фильтровать результаты по основному типу места.
Место также может иметь несколько значений типов из таблицы типов, связанных с ним. Например, ресторан может иметь следующие типы: "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 из запроса, поиск вернет места для всех типов в пределах границ ограничения местоположения.
включенные типы
Разделенный запятыми список типов мест из таблицы А для поиска. Если этот параметр опущен, возвращаются места всех типов.
исключенные типы
Список типов мест из таблицы А, разделенных запятыми, которые необходимо исключить из поиска.
Если вы укажете в запросе как includedTypes (например, "school" ), так и excludedTypes (например, "primary_school" ), то в ответ будут включены места, которые относятся к категории "school" но не к "primary_school" . Ответ включает места, соответствующие хотя бы одному из includedTypes и ни одному из excludedTypes .
Если есть какие-либо конфликтующие типы, например тип, присутствующий как в includedTypes , так и excludedTypes , возвращается ошибка INVALID_REQUEST .
включеноPrimaryTypes
Разделенный запятыми список основных типов мест из таблицы А для включения в поиск.
исключенные первичные типы
Разделенный запятыми список основных типов мест из таблицы А, которые необходимо исключить из поиска.
Если есть какие-либо конфликтующие первичные типы, например тип, встречающийся как в includedPrimaryTypes , так и excludedPrimaryTypes , возвращается ошибка INVALID_ARGUMENT .
языковой код
Язык, на котором возвращаются результаты.
- См. список поддерживаемых языков . Google часто обновляет поддерживаемые языки, поэтому этот список может быть неполным.
- Если languageCode не указан, API по умолчанию имеет значение en . Если вы укажете неверный код языка, API вернет ошибку INVALID_ARGUMENT .
- API делает все возможное, чтобы предоставить почтовый адрес, который будет удобен для чтения как пользователем, так и местными жителями. Для достижения этой цели он возвращает адреса на местном языке, транслитерированные в сценарий, который при необходимости читается пользователем, с учетом предпочтительного языка. Все остальные адреса возвращаются на предпочитаемом языке. Все компоненты адреса возвращаются на одном языке, выбранном из первого компонента.
- Если имя недоступно на предпочитаемом языке, API использует наиболее близкое совпадение.
- Предпочтительный язык оказывает небольшое влияние на набор результатов, которые API выбирает для возврата, и порядок их возврата. Геокодер интерпретирует сокращения по-разному в зависимости от языка, например сокращения типов улиц или синонимы, которые могут быть допустимы на одном языке, но недопустимы на другом.
МаксРезультатКаунт
Указывает максимальное количество возвращаемых результатов размещения. Должно быть от 1 до 20 (по умолчанию) включительно.
рангПредпочтение
Используемый тип рейтинга. Если этот параметр опущен, результаты ранжируются по популярности. Может быть одним из следующих:
- POPULARITY (по умолчанию) Сортирует результаты по популярности.
- DISTANCE Сортирует результаты в порядке возрастания по расстоянию от указанного местоположения.
Код региона
Код региона, используемый для форматирования ответа в виде двухсимвольного значения кода CLDR . Значения по умолчанию нет.
Если название страны в поле formattedAddress в ответе совпадает с regionCode , код страны в formattedAddress опускается. Этот параметр не влияет на adrFormatAddress , который всегда включает название страны, или на shortFormattedAddress , который никогда его не включает.
Большинство кодов CLDR идентичны кодам ISO 3166-1, за некоторыми заметными исключениями. Например, нДВУ Соединенного Королевства — «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.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

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

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

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

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

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

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

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

Маска поля

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

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

includeTypes/excludedTypes, includePrimaryTypes/excludedPrimaryTypes

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

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

включеноPrimaryTypes

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

языковой код

МаксРезультатКаунт

рангПредпочтение

Код региона

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

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

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

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

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

Попробуйте!