Find Place (устаревшая версия)

Запрос Find Place (Legacy) принимает текстовое значение и возвращает место. Ввести можно любые текстовые данные о месте, например название, адрес или номер телефона. Запрос должен быть строкой. Запрос Find Place (Legacy) с использованием нестроковых данных, таких как координаты широты/долготы или код Plus Code, генерирует ошибку.

Запросы Find Place (Legacy)

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

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

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

• json (рекомендуется) – вывод в формате JSON (JavaScript Object Notation).
• xml указывает, что выходные данные должны быть в формате XML.

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

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

• ввод

  Текстовая строка, по которой выполняется поиск. Нужно указать название места, его адрес или номер телефона (например, "улица Центральная, 123" или "мэрия").

• inputtype

  Тип входных данных. Возможные значения: textquery или phonenumber. Номер требуется указать в международном формате: знак "+", за которым следуют код страны и сам номер телефона. Дополнительные сведения вы найдете в рекомендациях E.164 ITU.

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

• fields

  Важно! Запросы поиска мест (Legacy) и информации о местах (Legacy) возвращают разные поля. При запросах Place Search (Legacy) возвращается только часть полей, которые возвращаются при запросах Place Details (Legacy). Если нужное поле не было возвращено Поиском мест (Legacy), с помощью Поиска мест (Legacy) можно получить place_id, а затем использовать этот идентификатор места в запросе информации о местах (Legacy). Подробнее о полях, недоступных в запросе Place Search (Legacy)…

  Чтобы указать типы данных о местах, которые нужно возвращать, используйте параметр fields. (например, fields=formatted_address,name,geometry). Если вы указываете составные значения, используйте косую черту. (например, opening_hours/open_now).

  Поля делятся на три категории, которые оплачиваются по разным тарифам: основные данные, контактные данные и данные об атмосфере. Поля Basic оплачиваются по базовой цене, а поля Contact и Atmosphere – по более высокой ставке. Оплата по кодам Basic, Contact и Atmosphere начисляется в дополнение к оплате по базовому коду (Places Details, Find Place, Nearby Search или Text Search) за запрос, который их активировал. Ознакомьтесь с информацией о ценах.

  Basic

  К категории Basic относятся следующие поля: address_components, adr_address, business_status, formatted_address, geometry, icon, icon_mask_base_uri, icon_background_color, name, permanently_closed (поддержка прекращена), photo, place_id, plus_code, type, url, utc_offset, vicinity, wheelchair_accessible_entrance.

  Контакт

  В категорию Contact входят следующие поля: current_opening_hours, formatted_phone_number, international_phone_number, opening_hours, secondary_opening_hours, website.

  Atmosphere

  Категория Atmosphere содержит следующие поля: curbside_pickup, delivery, dine_in, editorial_summary, price_level, rating, reservable, reviews, serves_beer, serves_breakfast, serves_brunch, serves_dinner, serves_lunch, serves_vegetarian_food, serves_wine, takeout, user_ratings_total.

  Примечание. С каждым вызовом возвращаются сведения об авторстве (html_attributions) независимо от того, запрашивалось ли это поле.

• language

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

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

• locationbias

  Предпочтение результатов из определенной области, заданной радиусом и координатами широты и долготы или двумя парами координат широты и долготы, представляющими точки прямоугольника. Если этот параметр не указан, API по умолчанию использует смещение по IP-адресу.

  • IP bias: указывает API использовать привязку к IP-адресу. Передайте строку ipbias (у этого варианта нет дополнительных параметров).
  • Круг: строка, в которой указан радиус в метрах, а также широта и долгота в десятичных градусах. Используйте следующий формат: circle:radius@lat,lng.
  • Прямоугольная область. Строка, содержащая две пары координат широты и долготы в десятичных градусах, которые представляют юго-западную и северо-восточную точки прямоугольника. Используйте следующий формат:rectangle:south,west|north,east. Обратите внимание, что значения для востока и запада находятся в диапазоне от -180 до 180, а для севера и юга – от -90 до 90.

Примеры использования Find Place (устаревший вариант)

Ниже приведен пример запроса Find Place (Legacy) для поиска "Museum of Contemporary Art Australia" с полями photos, formatted_address, name, rating, opening_hours и geometry.

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/findplacefromtext/json?input=Museum%20of%20Contemporary%20Art%20Australia&inputtype=textquery&fields=formatted_address%2Cname%2Crating%2Copening_hours%2Cgeometry&key=YOUR_API_KEY'

https://maps.googleapis.com/maps/api/place/findplacefromtext/json
    ?fields=formatted_address%2Cname%2Crating%2Copening_hours%2Cgeometry
    &input=Museum%20of%20Contemporary%20Art%20Australia
    &inputtype=textquery
    &key=YOUR_API_KEY

Ниже приведен пример запроса Find Place (Legacy) для поиска Mongolian Grill с параметром locationbias, который позволяет отдавать предпочтение результатам в пределах 2000 метров от указанных координат.

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/findplacefromtext/json?input=Mongolian%20Grill&inputtype=textquery&fields=formatted_address%2Cname%2Crating%2Copening_hours%2Cgeometry&locationbias=circle:2000@−33.866,151.216&key=YOUR_API_KEY'

https://maps.googleapis.com/maps/api/place/findplacefromtext/json
    ?fields=formatted_address%2Cname%2Crating%2Copening_hours%2Cgeometry
    &input=Mongolian%20Grill
    &inputtype=textquery
    &locationbias=circle:2000@−33.866,151.216
    &key=YOUR_API_KEY

Ниже приведен пример запроса Find Place (Legacy) для номера телефона. Обратите внимание, что префикс международного вызова "+" был закодирован как %2B, чтобы этот запрос был совместимым URL. Если не закодировать префикс +, он будет декодирован на сервере как пробел, что приведет к ошибке при поиске номера телефона.

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/findplacefromtext/json?input=%2B16502530000&inputtype=phonenumber&fields=formatted_address%2Cname%2Crating%2Copening_hours%2Cgeometry&key=YOUR_API_KEY'

https://maps.googleapis.com/maps/api/place/findplacefromtext/json
    ?fields=formatted_address%2Cname%2Crating%2Copening_hours%2Cgeometry
    &input=%2B16502530000
    &inputtype=phonenumber
    &key=YOUR_API_KEY

Ответы на запросы Find Place (Legacy)

Ответ Find Place (Legacy) содержит только типы данных, указанные с помощью параметра fields, а также html_attributions. Ниже приведен пример ответа на запрос Find Place (Legacy) для "Museum of Contemporary Art Australia" с полями formatted_address, geometry, name, opening_hours, photos и rating.

{
  "candidates":
    [
      {
        "formatted_address": "140 George St, The Rocks NSW 2000, Australia",
        "geometry":
          {
            "location": { "lat": -33.8599358, "lng": 151.2090295 },
            "viewport":
              {
                "northeast":
                  { "lat": -33.85824377010728, "lng": 151.2104386798927 },
                "southwest":
                  { "lat": -33.86094342989272, "lng": 151.2077390201073 },
              },
          },
        "name": "Museum of Contemporary Art Australia",
        "opening_hours": { "open_now": false },
        "rating": 4.4,
      },
    ],
  "status": "OK",
}    

<?xml version="1.0" encoding="UTF-8"?>
<FindPlaceFromTextResponse>
 <candidates>
  <name>Museum of Contemporary Art Australia</name>
  <formatted_address>140 George St, The Rocks NSW 2000, Australia</formatted_address>
  <geometry>
   <location>
    <lat>-33.8599358</lat>
    <lng>151.2090295</lng>
   </location>
   <viewport>
    <southwest>
     <lat>-33.8609434</lat>
     <lng>151.2077390</lng>
    </southwest>
    <northeast>
     <lat>-33.8582438</lat>
     <lng>151.2104387</lng>
    </northeast>
   </viewport>
  </geometry>
  <rating>4.4</rating>
  <opening_hours>
   <open_now>false</open_now>
  </opening_hours>
 </candidates>
 <status>OK</status>
</FindPlaceFromTextResponse>

    

PlacesFindPlaceFromTextResponse

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 в запросе информация о местах (устаревшая версия). Информацию о доступности полей и уровнях цен для конечных точек можно найти в статье Поля данных о местах (устаревшие).