Поиск поблизости (устаревший)

Разработчики из Европейской экономической зоны (ЕЭЗ)

Nearby Search (Legacy) позволяет искать места в указанной области. Вы можете уточнить поисковый запрос, указав ключевые слова или тип места, которое вы ищете.

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

Запрос Nearby Search (Legacy) – это URL с протоколом HTTP следующего формата:

https://maps.googleapis.com/maps/api/place/nearbysearch/output?parameters

где output может принимать одно из следующих значений:

  • json (рекомендуется) – вывод в формате JSON (JavaScript Object Notation).
  • xml – вывод в формате XML.

Для выполнения запроса Nearby Search (Legacy) требуются определенные параметры. Параметры разделяются амперсандами (&) в соответствии со стандартом написания URL.

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

местоположение

Точка, вокруг которой нужно получить информацию о местах. Необходимо указать значение latitude,longitude.

радиус

Определяет расстояние (в метрах), в пределах которого нужно возвращать результаты. С помощью параметров location и radius можно настроить поиск так, чтобы предпочтение отдавалось результатам в пределах указанной окружности. В этом случае сервис Places будет предпочитать результаты в пределах указанной области, однако более отдаленные точки также могут быть включены в ответ.

Радиус будет автоматически ограничен максимальным значением в зависимости от типа поиска и других параметров.

  • Автозаполнение: 50 000 метров.
  • Поиск поблизости:
    • с keyword или name – 50 000 метров;
    • без keyword или name
      • До 50 000 метров. Радиус корректируется динамически в зависимости от плотности застройки, независимо от параметра rankby.
      • При использовании rankby=distance параметр radius не принимается и возвращает ошибку INVALID_REQUEST.
  • Автозаполнение запросов: 50 000 м.
  • Текстовый поиск: 50 000 метров.

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

ключевое слово

Строка для текстового поиска, например "ресторан" или "улица Центральная, 123". Нужно указать название места, его адрес или категорию учреждения. Если ввести данные другого типа, вы можете получить неправильные результаты или возникнет ошибка. На основе этой строки сервис Google Places возвращает список подходящих мест, упорядоченных по их предполагаемой релевантности.

Явное указание информации о местоположении с помощью этого параметра может конфликтовать с параметрами location, radius и rankby, что приведет к неожиданным результатам.

Если этот параметр не указан, места со статусом CLOSED_TEMPORARILY или CLOSED_PERMANENTLY не возвращаются.

language

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

  • Вы можете ознакомиться со списком поддерживаемых языков. Google часто обновляет список поддерживаемых языков, поэтому он может быть неполным.
  • Если параметр language не указан, API пытается использовать язык, заданный в заголовке Accept-Language.
  • API пытается предоставить почтовый адрес, который будет понятен как пользователю, так и местным жителям. Для этого он возвращает почтовые адреса на местном языке, при необходимости транслитерируя их в систему письма, понятную пользователю, с учетом предпочитаемого языка. Все остальные адреса возвращаются на предпочитаемом языке. Все компоненты адреса возвращаются на одном языке, который выбирается по первому компоненту.
  • Если название на выбранном языке недоступно, API использует наиболее близкое совпадение.
  • Предпочтительный язык немного влияет на набор результатов, возвращаемых API, и на порядок их возврата. Геокодер по-разному интерпретирует сокращения в зависимости от языка. Например, это касается сокращений для типов улиц или синонимов, которые могут быть допустимы в одном языке, но не в другом. Например, utca и tér – это синонимы слова "улица" на венгерском языке.

maxprice

Ограничивает результаты местами, которые соответствуют указанному диапазону. Значения могут находиться в диапазоне от 0 (наиболее доступные места) до 4 (наиболее дорогие места). Точная сумма, соответствующая определенному значению, зависит от региона.

minprice

Ограничивает результаты местами, которые соответствуют указанному диапазону. Значения могут находиться в диапазоне от 0 (наиболее доступные места) до 4 (наиболее дорогие места). Точная сумма, соответствующая определенному значению, зависит от региона.

name

Аналогичен элементу keyword. Значения из этого поля объединяются со значениями поля keyword и передаются в составе той же строки поиска.

opennow

Возвращает только те места, которые открыты в момент отправки запроса. Если в запросе указан этот параметр, то все места, для которых в базе данных Google Places не указаны часы работы, игнорируются.

pagetoken

Возвращает до 20 результатов ранее выполненного поиска. Если задать параметр pagetoken, будет выполнен поиск с теми же параметрами, что и ранее. Все параметры, кроме pagetoken, будут игнорироваться.

rankby

Определяет порядок, в котором перечисляются результаты. Возможные значения:

  • prominence (по умолчанию). Результаты сортируются по известности. Приоритет в рейтинге отдается более известным местам, находящимся в заданной области, перед менее известными местами поблизости. На известность влияет рейтинг места в индексе Google, общая популярность и другие факторы. Если указано значение prominence, требуется также указать параметр radius.
  • distance. Результаты сортируются в порядке близости к точке, заданной в параметре location. Если вы укажете значение distance, нужно также предоставить keyword, name и/или type. При этом значение radius не допускается.

тип

В результаты поиска включаются только места указанного типа. Можно указать только один тип. Если указано несколько типов, API игнорирует все типы, кроме первого.

  • type=hospital|pharmacy|doctor становится type=hospital
  • type=hospital,pharmacy,doctor полностью игнорируется

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

Примечание. Если добавить и keyword, и type с одинаковым значением (keyword=cafe&type=cafe или keyword=parking&type=parking), может возникнуть ошибка ZERO_RESULTS.

Пример поиска поблизости (устаревшая версия)

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/nearbysearch/json?location=-33.8670522%2C151.1957362&radius=1500&type=restaurant&keyword=cruise&key=YOUR_API_KEY'

HTTP

https://maps.googleapis.com/maps/api/place/nearbysearch/json
  ?keyword=cruise
  &location=-33.8670522%2C151.1957362
  &radius=1500
  &type=restaurant
  &key=YOUR_API_KEY

Примечание. Чтобы запрос работал в вашем приложении, замените key собственным ключом API.

Ответы на запросы поиска мест рядом (устаревшая версия)

Ниже приведен пример ответа на запрос Nearby Search (Legacy).

JSON

{
  "html_attributions": [],
  "results":
    [
      {
        "business_status": "OPERATIONAL",
        "geometry":
          {
            "location": { "lat": -33.8587323, "lng": 151.2100055 },
            "viewport":
              {
                "northeast":
                  { "lat": -33.85739847010727, "lng": 151.2112436298927 },
                "southwest":
                  { "lat": -33.86009812989271, "lng": 151.2085439701072 },
              },
          },
        "icon": "https://maps.gstatic.com/mapfiles/place_api/icons/v1/png_71/bar-71.png",
        "icon_background_color": "#FF9E67",
        "icon_mask_base_uri": "https://maps.gstatic.com/mapfiles/place_api/icons/v2/bar_pinlet",
        "name": "Cruise Bar",
        "opening_hours": { "open_now": false },
        "photos":
          [
            {
              "height": 608,
              "html_attributions":
                [
                  'A Google User',
                ],
              "photo_reference": "Aap_uECvJIZuXT-uLDYm4DPbrV7gXVPeplbTWUgcOJ6rnfc4bUYCEAwPU_AmXGIaj0PDhWPbmrjQC8hhuXRJQjnA1-iREGEn7I0ZneHg5OP1mDT7lYVpa1hUPoz7cn8iCGBN9MynjOPSUe-UooRrFw2XEXOLgRJ-uKr6tGQUp77CWVocpcoG",
              "width": 1080,
            },
          ],
        "place_id": "ChIJi6C1MxquEmsR9-c-3O48ykI",
        "plus_code":
          {
            "compound_code": "46R6+G2 The Rocks, New South Wales",
            "global_code": "4RRH46R6+G2",
          },
        "price_level": 2,
        "rating": 4,
        "reference": "ChIJi6C1MxquEmsR9-c-3O48ykI",
        "scope": "GOOGLE",
        "types":
          ["bar", "restaurant", "food", "point_of_interest", "establishment"],
        "user_ratings_total": 1269,
        "vicinity": "Level 1, 2 and 3, Overseas Passenger Terminal, Circular Quay W, The Rocks",
      },
      {
        "business_status": "OPERATIONAL",
        "geometry":
          {
            "location": { "lat": -33.8675219, "lng": 151.2016502 },
            "viewport":
              {
                "northeast":
                  { "lat": -33.86614532010728, "lng": 151.2031259298927 },
                "southwest":
                  { "lat": -33.86884497989272, "lng": 151.2004262701072 },
              },
          },
        "icon": "https://maps.gstatic.com/mapfiles/place_api/icons/v1/png_71/generic_business-71.png",
        "icon_background_color": "#7B9EB0",
        "icon_mask_base_uri": "https://maps.gstatic.com/mapfiles/place_api/icons/v2/generic_pinlet",
        "name": "Sydney Harbour Dinner Cruises",
        "opening_hours": { "open_now": true },
        "photos":
          [
            {
              "height": 835,
              "html_attributions":
                [
                  'A Google User',
                ],
              "photo_reference": "Aap_uEBVsYnNcrpRixtrlHBztigZh70CwYkNWZzQnqJ39SjeBo_wvgKf-kXc6tgaMLBdQrRKmxmSKjOezoZrv-sHKVbTX0OI48HBqYYVnQiZQ-WGeuQDsLEPwX7LaVPa68nUAxX114Zpqt7bryoO9wL4qXdgEnopbOp5WWLALhKEHoIEH7f7",
              "width": 1200,
            },
          ],
        "place_id": "ChIJM1mOVTS6EmsRKaDzrTsgids",
        "plus_code":
          {
            "compound_code": "46J2+XM Sydney, New South Wales",
            "global_code": "4RRH46J2+XM",
          },
        "rating": 4.8,
        "reference": "ChIJM1mOVTS6EmsRKaDzrTsgids",
        "scope": "GOOGLE",
        "types":
          [
            "tourist_attraction",
            "travel_agency",
            "restaurant",
            "food",
            "point_of_interest",
            "establishment",
          ],
        "user_ratings_total": 9,
        "vicinity": "32 The Promenade, Sydney",
      },
      // ...
    ],
  "status": "OK",
}

XML

<?xml version="1.0" encoding="UTF-8"?>
<PlaceSearchResponse>
 <status>OK</status>
 <result>
  <name>Cruise Bar</name>
  <vicinity>Level 1, 2 and 3, Overseas Passenger Terminal, Circular Quay W, The Rocks</vicinity>
  <type>bar</type>
  <type>restaurant</type>
  <type>food</type>
  <type>point_of_interest</type>
  <type>establishment</type>
  <geometry>
   <location>
    <lat>-33.8587323</lat>
    <lng>151.2100055</lng>
   </location>
   <viewport>
    <southwest>
     <lat>-33.8600981</lat>
     <lng>151.2085440</lng>
    </southwest>
    <northeast>
     <lat>-33.8573985</lat>
     <lng>151.2112436</lng>
    </northeast>
   </viewport>
  </geometry>
  <rating>4.0</rating>
  <icon>https://maps.gstatic.com/mapfiles/place_api/icons/v1/png_71/bar-71.png</icon>
  <reference>ChIJi6C1MxquEmsR9-c-3O48ykI</reference>
  <opening_hours>
   <open_now>false</open_now>
  </opening_hours>
  <photo>
   <photo_reference>Aap_uEALIq4sgBHhIYWWapOH2NV1T2I7YdOiLzEH7z-483I764cId1sZkbzSq-hVYTk1PQeaHuZzlRfA7-ilwJ3QWon4b37ePd-PBwZbOwFZHxhYs0Cs7jRSgMHWfOzGivp6ZFG4iupyz50qS5pBZT1WbA2ufacTq_U21TtgffQD31wKRPQk</photo_reference>
   <width>1080</width>
   <height>608</height>
   <html_attribution>&lt;a href=&quot;https://maps.google.com/maps/contrib/112582655193348962755&quot;&gt;A Google User&lt;/a&gt;</html_attribution>
  </photo>
  <price_level>2</price_level>
  <user_ratings_total>1269</user_ratings_total>
  <place_id>ChIJi6C1MxquEmsR9-c-3O48ykI</place_id>
  <scope>GOOGLE</scope>
  <plus_code>
   <global_code>4RRH46R6+G2</global_code>
   <compound_code>46R6+G2 The Rocks, New South Wales</compound_code>
  </plus_code>
  <icon_background_color>#FF9E67</icon_background_color>
  <business_status>OPERATIONAL</business_status>
  <icon_mask_base_uri>https://maps.gstatic.com/mapfiles/place_api/icons/v2/bar_pinlet</icon_mask_base_uri>
 </result>
 <result>
  <name>Sydney Harbour Dinner Cruises</name>
  <vicinity>32 The Promenade, Sydney</vicinity>
  <type>tourist_attraction</type>
  <type>restaurant</type>
  <type>food</type>
  <type>travel_agency</type>
  <type>point_of_interest</type>
  <type>establishment</type>
  <geometry>
   <location>
    <lat>-33.8675219</lat>
    <lng>151.2016502</lng>
   </location>
   <viewport>
    <southwest>
     <lat>-33.8688450</lat>
     <lng>151.2004263</lng>
    </southwest>
    <northeast>
     <lat>-33.8661453</lat>
     <lng>151.2031259</lng>
    </northeast>
   </viewport>
  </geometry>
  <rating>4.8</rating>
  <icon>https://maps.gstatic.com/mapfiles/place_api/icons/v1/png_71/generic_business-71.png</icon>
  <reference>ChIJM1mOVTS6EmsRKaDzrTsgids</reference>
  <opening_hours>
   <open_now>true</open_now>
  </opening_hours>
  <photo>
   <photo_reference>Aap_uEB5jH7GXdcozv1Y5HX18syo4f128S58NVUnqBbLJMpWbC39K49wp-wzsLOsUT8QKDaag6ISFL8hl1vVuig4jkc5fMMkWKiqw5PY-ebcWZ5tI3gEXEYGGoG_mDAulaMLudUpSwgBx2_RLnA0SSiugqqQUTYlkGyCZSe8HSyngVczy6XN</photo_reference>
   <width>1200</width>
   <height>835</height>
   <html_attribution>&lt;a href=&quot;https://maps.google.com/maps/contrib/109764923610545394994&quot;&gt;A Google User&lt;/a&gt;</html_attribution>
  </photo>
  <user_ratings_total>9</user_ratings_total>
  <place_id>ChIJM1mOVTS6EmsRKaDzrTsgids</place_id>
  <scope>GOOGLE</scope>
  <plus_code>
   <global_code>4RRH46J2+XM</global_code>
   <compound_code>46J2+XM Sydney, New South Wales</compound_code>
  </plus_code>
  <icon_background_color>#7B9EB0</icon_background_color>
  <business_status>OPERATIONAL</business_status>
  <icon_mask_base_uri>https://maps.gstatic.com/mapfiles/place_api/icons/v2/generic_pinlet</icon_mask_base_uri>
 </result>
 <!-- ... -->
</PlaceSearchResponse>

PlacesNearbySearchResponse

Поле Обязательно Тип Описание
Обязательно Array<string>

Может содержать набор атрибутов, которые должны быть показаны пользователю (у некоторых объектов атрибуты могут отсутствовать).

Обязательно Массив<Place>

Содержит массив мест.

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

Подробнее о местах…
Обязательно PlacesSearchStatus

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

Подробную информацию можно найти в разделе PlacesSearchStatus.

необязательно string

Если сервис возвращает код статуса, отличный от OK<, в объекте ответа может присутствовать дополнительное поле error_message. В этом поле содержится более подробная информация о причинах, по которым был присвоен тот или иной код статуса. Это поле возвращается не всегда, и его содержимое может меняться.

необязательно Array<string>

Если сервис возвращает дополнительную информацию о спецификации запроса, в объекте ответа может быть дополнительное поле info_messages. Это поле возвращается только для успешных запросов. Оно может возвращаться не всегда, а его содержимое может меняться.

next_page_token

необязательно string

Содержит токен, с помощью которого можно получить до 20 дополнительных результатов. Если дополнительных результатов нет, то next_page_token не возвращается. Максимальное количество результатов, которое может быть возвращено, – 60. Между выдачей токена next_page_token и моментом, когда он станет действительным, проходит некоторое время.

PlacesSearchStatus

Коды статуса, возвращаемые сервисом.

  • OK означает, что запрос к API успешно выполнен;
  • ZERO_RESULTS – означает, что поиск успешно выполнен, однако результаты не найдены. Такое может произойти, если в поиске был передан адрес latlng в удаленном местоположении.
  • INVALID_REQUEST означает, что запрос к API был составлен неправильно, обычно из-за отсутствия обязательного параметра запроса (location или radius).
  • OVER_QUERY_LIMIT, указывающий на любое из следующего:
    • Вы превысили лимиты на количество запросов в секунду.
    • В вашем аккаунте не включены платежные функции.
    • Превышен месячный бонус в размере 200 долларов США или заданное ограничение на использование.
    • Указанный способ оплаты больше не действует (например, истек срок действия кредитной карты).
    Дополнительную информацию о том, как устранить эту ошибку, можно найти в разделе часто задаваемых вопросов о Картах.
  • REQUEST_DENIED указывает, что запрос был отклонен. Обычно это происходит по следующим причинам:
    • В запросе отсутствует ключ API.
    • Недопустимый параметр key.
  • UNKNOWN_ERROR означает неизвестную ошибку.

Место

Ответы поиска мест возвращают следующее подмножество полей Place. Не все атрибуты доступны для всех типов мест. Чтобы получить поля, которые не возвращает поиск мест, например address_components, formatted_phone_number, reviews или website, передайте возвращенный place_id в запросе информация о местах (устаревшая версия). Информацию о доступности полей и уровнях цен для конечных точек можно найти в статье Поля данных о местах (устаревшие).

Поле Тип Описание
business_status string Указывает, работает ли место, если оно является компанией: OPERATIONAL, CLOSED_TEMPORARILY или CLOSED_PERMANENTLY. Если данных о статусе нет, это поле не показывается.
formatted_address string Человекочитаемый адрес этого места. Возвращается методами Text Search (Legacy) и Find Place (Legacy). Не анализируйте отформатированный адрес программно. Вместо этого запросите address_components в Place Details (Legacy).
geometry Geometry Содержит геокодированное значение location с координатами lat и lng, а также предпочтительное значение viewport с границами northeast и southwest.
icon string URL рекомендуемого значка, который можно использовать для обозначения этого результата на карте.
icon_background_color string Шестнадцатеричный код цвета по умолчанию для категории места.
icon_mask_base_uri string Базовый URL рекомендуемого значка без расширения типа файла SVG или PNG.
name string Человекочитаемое название результата. Для результатов типа establishment это значение обычно представляет собой канонизированное название компании.
opening_hours PlaceOpeningHours Часы работы. Конечные точки поиска мест возвращают только логическое подполе open_now. Запросите opening_hours в информации о местах (устаревшая версия) для periods и weekday_text.
permanently_closed boolean Устарело. Используйте business_status, чтобы проверить статус компании.
photos Array<PlacePhoto> Массив объектов PlacePhoto, каждый из которых содержит photo_reference, height, width и html_attributions. Подробные сведения об использовании приведены в разделе Фотографии мест (устаревшие).
place_id string уникальный текстовый идентификатор места. Передайте этот идентификатор в параметре place_id устаревшего запроса Place Details. Подробнее об идентификаторе места…
plus_code PlusCode Закодированное местоположение, полученное на основе координат широты и долготы, содержащее global_code и необязательный compound_code.
price_level integer Уровень цен в месте по шкале от 0 до 4 (от самого дешевого до самого дорогого). Подробнее: price_level.
rating number Оценка места в диапазоне от 1.0 до 5.0, основанная на отзывах пользователей.
reference string Устарело. Используйте place_id.
scope string Устарело. Указывает область действия place_id, которая всегда равна GOOGLE. Возвращается методом Nearby Search (Legacy).
types Array<string> Массив типов объектов, описывающих данный результат. Подробнее о типах мест (устаревшая версия)…
user_ratings_total integer Общее количество оценок этого места (с текстом отзыва или без него).
vicinity string Упрощенный адрес места, включая населенный пункт, улицу и номер дома, но без указания штата, провинции или области, почтового индекса и страны. Возвращается методом Nearby Search (Legacy).

Отображение дополнительных результатов

По умолчанию в каждом ответе возвращается до 20 результатов типа establishment на запрос. Однако всего количество результатов может доходить до 60, и в таком случае они разбиваются на три страницы. Если результатов больше 20, в ответе на поисковый запрос будет дополнительное значение – next_page_token. Чтобы увидеть следующий набор результатов, передайте значение next_page_token в параметр pagetoken нового запроса.

  • Если next_page_token имеет значение null или не возвращается, значит, результатов больше нет.
  • Повторный запрос с тем же значением next_page_token вернет следующую страницу результатов.
  • Если задать параметр pagetoken, все остальные параметры будут игнорироваться.
  • После первоначального запроса вы можете запросить новую страницу до двух раз.
  • Каждый запрос, в том числе с использованием next_page_token, учитывается как отдельный запрос в рамках лимитов на использование и оплачивается отдельно.
  • Между выпуском next_page_token и началом его действия проходит несколько секунд. Если вы запросите следующую страницу до того, как она станет доступна, то получите ответ INVALID_REQUEST. Запросы с next_page_token всегда оплачиваются.

Например, в запросе ниже мы ищем рестораны рядом с гаванью Дарлинг в Сиднее (Австралия) и ранжируем результаты по расстоянию. В ответе есть свойство next_page_token.

{
   "html_attributions" : [],
   "next_page_token" : "CpQCAgEAAFxg8o-eU7_uKn7Yqjana-HQIx1hr5BrT4zBaEko29ANsXtp9mrqN0yrKWhf-y2PUpHRLQb1GT-mtxNcXou8TwkXhi1Jbk-ReY7oulyuvKSQrw1lgJElggGlo0d6indiH1U-tDwquw4tU_UXoQ_sj8OBo8XBUuWjuuFShqmLMP-0W59Vr6CaXdLrF8M3wFR4dUUhSf5UC4QCLaOMVP92lyh0OdtF_m_9Dt7lz-Wniod9zDrHeDsz_by570K3jL1VuDKTl_U1cJ0mzz_zDHGfOUf7VU1kVIs1WnM9SGvnm8YZURLTtMLMWx8-doGUE56Af_VfKjGDYW361OOIj9GmkyCFtaoCmTMIr5kgyeUSnB-IEhDlzujVrV6O9Mt7N4DagR6RGhT3g1viYLS4kO5YindU6dm3GIof1Q",
   "results" : [...]
   "status" : "OK"
}

Чтобы увидеть следующий набор результатов, отправьте новый запрос, передав результат next_page_token в параметр pagetoken. Пример: 

https://maps.googleapis.com/maps/api/place/nearbysearch/json?pagetoken=CpQCAgEAAFxg8o-eU7_uKn7Yqjana-HQIx1hr5BrT4zBaEko29ANsXtp9mrqN0yrKWhf-y2PUpHRLQb1GT-mtxNcXou8TwkXhi1Jbk-ReY7oulyuvKSQrw1lgJElggGlo0d6indiH1U-tDwquw4tU_UXoQ_sj8OBo8XBUuWjuuFShqmLMP-0W59Vr6CaXdLrF8M3wFR4dUUhSf5UC4QCLaOMVP92lyh0OdtF_m_9Dt7lz-Wniod9zDrHeDsz_by570K3jL1VuDKTl_U1cJ0mzz_zDHGfOUf7VU1kVIs1WnM9SGvnm8YZURLTtMLMWx8-doGUE56Af_VfKjGDYW361OOIj9GmkyCFtaoCmTMIr5kgyeUSnB-IEhDlzujVrV6O9Mt7N4DagR6RGhT3g1viYLS4kO5YindU6dm3GIof1Q&key=YOUR_API_KEY