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

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

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

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

    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.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 для доступа к текстовому названию места.

  • Следующие поля активируют SKU Nearby Search Enterprise :

    places.currentOpeningHours
places.currentSecondaryOpeningHours
places.internationalPhoneNumber
places.nationalPhoneNumber
places.priceLevel
places.priceRange
places.rating
places.regularOpeningHours
places.regularSecondaryOpeningHours
places.userRatingCount
places.websiteUri

  • Следующие поля активируют SKU Nearby Search Enterprise Plus :

    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.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
    }
  }

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

• 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 .

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

  Разделенный запятыми список основных типов мест из таблицы А для включения в поиск.

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

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

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

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

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

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

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