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

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

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

Примечание о серверных и клиентских библиотеках

Places API также доступен в клиентах Java, Python, Go и Node.js для сервисов Google Карт. Places API и клиентские библиотеки предназначены для использования в серверных приложениях.

Если вы разрабатываете клиентское приложение, ознакомьтесь с документацией по Places SDK для Android (новая версия), Places SDK для iOS (новая версия) и библиотеке Places в Maps JavaScript API.

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

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

Запросы 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" или "мэрия").

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

inputtype

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

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

fields

Внимание! Запросы поиска мест (Legacy) и информация о местах (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.

Примечание. Если вы не укажете параметр fields в запросе Find Place (Legacy), в ответе будет возвращено только поле place_id.

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

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

curl

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'

HTTP

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

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'

HTTP

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

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'

HTTP

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.

JSON

{
  "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

<?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

Поле	Обязательно	Тип	Описание
`candidates`	Обязательно	Массив<Place>	Содержит массив кандидатов на место. При запросах Поиск мест (устаревший) возвращается только часть полей, которые возвращаются при запросах информация о местах (устаревший). Если нужное поле не было возвращено Place Search (Legacy), с помощью Place Search (Legacy) можно получить идентификатор места, а затем использовать его в запросе Place Details (Legacy). Подробнее о местах…
`status`	Обязательно	PlacesSearchStatus	Содержит статус запроса и может содержать сведения для отладки, которые помогут вам выяснить, почему запрос не был выполнен. Подробную информацию можно найти в разделе PlacesSearchStatus.
`error_message`	необязательно	string	Если сервис возвращает код статуса, отличный от `OK<`, в объекте ответа может присутствовать дополнительное поле `error_message`. В этом поле содержится более подробная информация о причинах, по которым был присвоен тот или иной код статуса. Это поле возвращается не всегда, и его содержимое может меняться.
`info_messages`	необязательно	Array<string>	Если сервис возвращает дополнительную информацию о спецификации запроса, в объекте ответа может быть дополнительное поле `info_messages`. Это поле возвращается только для успешных запросов. Оно может возвращаться не всегда, а его содержимое может меняться.

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

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

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

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

ввод

inputtype

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

fields

language

locationbias

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

curl

HTTP

curl

HTTP

curl

HTTP

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

JSON

XML

PlacesFindPlaceFromTextResponse

`candidates`

`status`

`error_message`

`info_messages`

PlacesSearchStatus

Место

Find Place (устаревшая версия) Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.

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

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

ввод

inputtype

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

fields

language

locationbias

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

curl

HTTP

curl

HTTP

curl

HTTP

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

JSON

XML

PlacesFindPlaceFromTextResponse

candidates

status

error_message

info_messages

PlacesSearchStatus

Место

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

`candidates`

`status`

`error_message`

`info_messages`