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

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

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

    • Следующие поля активируют 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 типов.

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

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

    Список типов мест из таблицы 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

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

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

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

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

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

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