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

Выберите платформу: 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: *

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

    • Следующие поля активируют SKU «Поиск поблизости (базовый)» :

      places.accessibilityOptions , places.addressComponents , places.adrFormatAddress , places.attributions , places.businessStatus , places.displayName , places.formattedAddress , places.googleMapsUri , places.iconBackgroundColor , places.iconMaskBaseUri , places.id , places.location , places.name * , places.photos , places.plusCode , places.primaryType , places.primaryTypeDisplayName , places.shortFormattedAddress , places.subDestinations , places.types , places.utcOffsetMinutes , places.viewport

      * Поле places.name содержит имя ресурса места в форме: places/ PLACE_ID . Используйте places.displayName для доступа к текстовому названию места.

    • Следующие поля активируют SKU «Поиск поблизости (расширенный)» :

      places.currentOpeningHours , places.currentSecondaryOpeningHours , places.internationalPhoneNumber , places.nationalPhoneNumber , places.priceLevel , 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.servesCoffee places.servesBrunch , places.servesCocktails , 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 типов.

    Место может иметь только один основной тип из таблицы типов, связанных с ним. Например, основным типом может быть "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 (например, "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.

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