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

Выберите платформу: Android iOS JavaScript Веб-сервис
Разработчики из Европейской экономической зоны (ЕЭЗ)

Введение

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

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

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

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

Запрос Nearby Search (новый) представляет собой 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)
    }
  ]
}

Необходимые параметры

  • FieldMask

    Укажите список полей, которые должны быть возвращены в ответе, создав маску полей ответа . Передайте маску полей ответа методу, используя параметр URL $fields или fields , или используя HTTP-заголовок X-Goog-FieldMask . В ответе нет списка возвращаемых полей по умолчанию. Если вы опустите маску полей, метод вернет ошибку.

    Использование маскирования полей — это хорошая практика проектирования, позволяющая избежать запроса ненужных данных, что помогает избежать лишнего времени обработки и дополнительных расходов на выставление счетов.

    Укажите список типов данных мест, разделенных запятыми, которые необходимо вернуть. Например, чтобы получить отображаемое имя и адрес места.

    X-Goog-FieldMask: places.displayName,places.formattedAddress

    Используйте * для получения всех полей.

    X-Goog-FieldMask: *

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

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

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

      * Только текстовый поиск и поиск поблизости

  • locationRestriction

    Область поиска задается в виде круга, определяемого центральной точкой и радиусом в метрах. Радиус должен находиться в диапазоне от 0,0 до 50000,0 включительно. Радиус по умолчанию равен 0,0. В вашем запросе необходимо указать значение больше 0,0.

    Например: 

    "locationRestriction": {
  "circle": {
    "center": {
      "latitude": 37.7937,
      "longitude": -122.3965
    },
    "radius": 500.0
  }
}

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

  • includedTypes/excludedTypes, includedPrimaryTypes/excludedPrimaryTypes

    Позволяет указать список типов из таблицы типов A, используемых для фильтрации результатов поиска. В каждой категории ограничения типов можно указать до 50 типов.

    Для каждого заведения может быть только один основной тип из таблицы типов 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" .

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

    Список типов мест из таблицы А , разделенных запятыми, для поиска. Если этот параметр опущен, возвращаются места всех типов.

    excludedTypes

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

    Если в запросе указаны как includedTypes (например, "school" ), так и excludedTypes типы (например, "primary_school" ), то ответ будет включать места, которые классифицируются как "school" , но не как "primary_school" . Ответ будет включать места, которые соответствуют хотя бы одному из includedTypes и ни одному из excludedTypes .

    Если возникают конфликтующие типы, например, тип присутствует как в includedTypes , так и excludedTypes , возвращается ошибка INVALID_REQUEST .

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

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

    excludedPrimaryTypes

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

    Если существуют конфликтующие первичные типы, например, тип присутствует как в includedPrimaryTypes , так и excludedPrimaryTypes , возвращается ошибка INVALID_ARGUMENT .

  • languageCode

    Язык, на котором будут возвращаться результаты.

    • См. список поддерживаемых языков . Google часто обновляет список поддерживаемых языков, поэтому этот список может быть неполным.
    • Если languageCode не указан, API по умолчанию использует en . Если вы укажете недопустимый код языка, API вернет ошибку INVALID_ARGUMENT .
    • API делает все возможное, чтобы предоставить уличный адрес, понятный как пользователю, так и местным жителям. Для достижения этой цели он возвращает уличные адреса на местном языке, при необходимости транслитерированные в письменность, понятную пользователю, с учетом предпочтительного языка. Все остальные адреса возвращаются на предпочтительном языке. Все компоненты адреса возвращаются на одном языке, который выбирается из первого компонента.
    • Если имя недоступно на предпочитаемом языке, API использует наиболее близкое совпадение.
    • Предпочитаемый язык оказывает незначительное влияние на набор результатов, которые API выбирает для возврата, и на порядок их возврата. Геокодер по-разному интерпретирует сокращения в зависимости от языка, например, сокращения для типов улиц или синонимы, которые могут быть допустимы в одном языке, но не в другом.

  • maxResultCount

    Указывает максимальное количество результатов поиска мест, которые необходимо вернуть. Должно быть от 1 до 20 (по умолчанию) включительно.

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

    Тип используемого ранжирования. Если этот параметр опущен, результаты ранжируются по популярности. Может принимать одно из следующих значений:

    • POPULARITY (по умолчанию) Сортирует результаты по их популярности.
    • DISTANCE сортирует результаты в порядке возрастания расстояния от указанного местоположения.

  • regionCode

    Региональный код, используемый для форматирования ответа, указывается в виде двухсимвольного кода 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.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

Получить описания адресов

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

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

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

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

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

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