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

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

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.
    • Query Autocomplete: 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. Результаты поиска сортируются в порядке возрастания расстояния от указанного местоположения. Если вы укажете значение 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.

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

В примере ниже показан ответ на запрос поиска поблизости (устаревшая версия).

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, а затем использовать этот идентификатор места в запросе информации о местах.

Подробнее о типе Place…
Обязательно 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 Человекочитаемый адрес этого места. Возвращается методами текстового поиска (устаревшая версия) и Find Place (устаревшая версия). Не анализируйте отформатированный адрес программно. Вместо этого запросите 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 Deprecated. Указывает область действия 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