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

Autocomplete (New)

Выберите платформу: Android iOS JavaScript Веб-сервисы

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

Введение

Новый сервис автозаполнения – это веб-сервис, который возвращает подсказки мест и запросов в ответ на HTTP-запрос. В запросе укажите строку текстового поиска и географические границы, определяющие область поиска.

Новый сервис автозаполнения может обрабатывать полные слова и их части, предлагая подходящие названия мест, адреса и коды Plus Code. Приложения могут передавать запросы по мере их ввода и сразу же предлагать похожие варианты.

Ответ от сервиса "Автозаполнение (новая версия)" может содержать два типа подсказок:

Прогнозы мест. Места, например компании, адреса и объекты инфраструктуры, на основе указанной текстовой строки и области поиска. По умолчанию возвращаются подсказки мест.
Подсказки запросов. Строки запросов, соответствующие введенной текстовой строке и области поиска. По умолчанию подсказки запросов не возвращаются. Чтобы добавить в ответ подсказки, используйте параметр запроса includeQueryPredictions.

Например, вы вызываете функцию Autocomplete (New), используя в качестве входных данных строку, содержащую частичный ввод пользователя, "сицилийская пиц", при этом область поиска ограничена Сан-Франциско, Калифорния. В ответе содержится список подсказок мест, соответствующих строке и области поиска, например ресторан "Сицилийская пицца", а также сведения о месте.

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

Ответ также может содержать список подсказок, соответствующих поисковому запросу и области поиска, например "Пицца и паста по-сицилийски". Каждая подсказка в ответе содержит поле text с рекомендуемой строкой текстового поиска. Используйте эту строку в качестве входных данных для нового текстового поиска, чтобы выполнить более подробный поиск.

API Explorer позволяет отправлять запросы в реальном времени, чтобы вы могли ознакомиться с API и его возможностями:

Попробовать

Запросы к Autocomplete API (новая версия)

Запрос автозаполнения (новый) – это HTTP-запрос POST к URL в следующем формате:

https://places.googleapis.com/v1/places:autocomplete

Передайте все параметры в теле запроса JSON или в заголовках как часть запроса POST. Пример:

curl -X POST -d '{
  "input": "pizza",
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965
      },
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

Поддерживаемые параметры

Параметр	Описание
`input`*	Текстовая строка для поиска (полные слова, подстроки, названия мест, адреса, коды Plus Code).
`FieldMask` (заголовок HTTP)	Список полей, которые должны быть возвращены в ответе, разделенный запятыми.
`includedPrimaryTypes`	Ограничивает результаты поиска местами, соответствующими одному из пяти указанных основных типов.
`includePureServiceAreaBusinesses`	Если значение равно true, то в результаты поиска включаются компании без физического адреса (обслуживающие определенную территорию). Значение по умолчанию – false.
`includeQueryPredictions`	Если задано значение true, в ответе будут содержаться как подсказки мест, так и подсказки запросов. Значение по умолчанию – false.
`includedRegionCodes`	Массив, содержащий до 15 двухбуквенных кодов стран, в которых нужно искать результаты.
`inputOffset`	Смещение символа Unicode от позиции курсора в строке ввода, влияющее на подсказки. Нумерация начинается с нуля. По умолчанию используется длина входных данных.
`languageCode`	Предпочитаемый язык результатов (код IETF BCP-47). По умолчанию используется заголовок Accept-Language или "en".
`locationBias`	Задает область (круг или прямоугольник), в которой предпочтительно искать результаты. Результаты за пределами этой области также могут быть показаны. Нельзя использовать вместе с locationRestriction.
`locationRestriction`	Задает область (круг или прямоугольник), в пределах которой нужно ограничить результаты поиска. Результаты за пределами этой области исключаются. Нельзя использовать вместе с параметром locationBias.
`origin`	Исходная точка (широта, долгота), используемая для расчета расстояния по прямой (distanceMeters) до прогнозируемых пунктов назначения.
`regionCode`	Код региона, используемый для форматирования ответа и подсказок (например, "uk", "fr").
`sessionToken`	Строка, созданная пользователем, чтобы сгруппировать вызовы Autocomplete в сеанс для выставления счетов.

* Обязательное поле.

Об ответе

Autocomplete (New) возвращает объект JSON в качестве ответа. В ответе:

Массив suggestions содержит все предсказанные места и запросы в порядке убывания их предполагаемой релевантности. Каждое место представлено полем placePrediction, а каждый запрос – полем queryPrediction.
Поле placePrediction содержит подробную информацию об одном прогнозе места, включая идентификатор места и текстовое описание.
- Чтобы точнее соответствовать введенным пользователем данным, которые передаются в параметре input, текстовое описание подсказки места может включать альтернативные названия мест, улиц и других компонентов адреса. Эти альтернативные названия могут отличаться от названий, возвращаемых в полях displayName и address в результатах запросов данных о месте для того же идентификатора места.
- В этом контексте альтернативные названия некоторых мест могут быть на другом языке, чем ожидается на основе параметра languageCode, в зависимости от того, какие названия больше соответствуют запросу пользователя.
Поле queryPrediction содержит подробную информацию об одном прогнозе запроса.

Примечание. Autocomplete (New) возвращает пять подсказок в виде placePredictions, queryPredictions или их комбинации в зависимости от запроса. Если в запросе не задано значение includeQueryPredictions, в ответе будет до пяти объектов placePredictions. Если в запросе задано значение includeQueryPredictions, ответ будет содержать до пяти подсказок, представляющих собой комбинацию placePredictions и queryPredictions.

Полный объект JSON имеет следующий вид:

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }]
        },
      ...
    },
    {
      "queryPrediction": {
        "text": {
          "text": "Amoeba Music",
          "matches": [
            {
              "endOffset": 6
            }]
        },
        ...
    }
  ...]
}

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

ввод

Строка, в которой нужно выполнить поиск. Укажите полные слова и их части, названия мест, адреса и коды Plus Code. Сервис "Автозаполнение (новая версия)" возвращает список подходящих мест, упорядоченных по их предполагаемой релевантности.

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

FieldMask

Укажите список полей, которые должны быть возвращены в ответе, создав маску поля ответа. Передайте маску поля ответа методу, используя заголовок HTTP X-Goog-FieldMask.

Укажите список полей подсказок, которые нужно вернуть, через запятую. Например, чтобы получить значения suggestions.placePrediction.text.text и suggestions.queryPrediction.text.text для рекомендации.
```
  X-Goog-FieldMask: suggestions.placePrediction.text.text,suggestions.queryPrediction.text.text
```
Примечание. В списке полей не должно быть пробелов.

Чтобы получить все поля, используйте *.
```
  X-Goog-FieldMask: *
```
includeFutureOpeningBusinesses

Если true, возвращает компании, которые планируется открыть в будущем. Значение по умолчанию – false.
includedPrimaryTypes

У места может быть только один основной тип из типов, перечисленных в таблице А или таблице Б. Например, основным типом может быть "mexican_restaurant" или "steak_house".

По умолчанию API возвращает все места на основе параметра input, независимо от значения основного типа, связанного с местом. Чтобы ограничить результаты поиска определенным основным типом или типами, передайте параметр includedPrimaryTypes.

Этот параметр позволяет указать до пяти значений типа из таблицы А или таблицы Б. Чтобы место было включено в ответ, оно должно соответствовать одному из указанных значений основного типа.

Вместо этого параметра можно также указать (regions) или (cities). Коллекция типов (regions) позволяет фильтровать области или районы, например микрорайоны и почтовые индексы. Коллекция типов (cities) позволяет фильтровать места, которые Google определяет как города.

Запрос отклоняется с ошибкой INVALID_REQUEST, если:
- Указано более пяти типов.
- Указан любой тип, кроме (cities) или (regions).
- указать неизвестный тип;
Примечание. Параметр includedPrimaryTypes работает только с основным типом места, а не со всеми типами, связанными с ним. Хотя у каждого места есть основной тип, не все основные типы поддерживаются в Places API (New). Поддерживаемые типы перечислены в таблице А и таблице Б.
includePureServiceAreaBusinesses

Если задано значение true, в ответ включаются компании, которые посещают клиентов или доставляют им товары напрямую, но не имеют физического адреса. Если задано значение false, API возвращает только компании с физическим адресом.
includeQueryPredictions

Если задано значение true, ответ включает подсказки как для мест, так и для запросов. Значение по умолчанию – false, то есть ответ включает только варианты мест.
includedRegionCodes

Включать в результаты только данные из указанных регионов. Можно задать до 15 ccTLD (доменов верхнего уровня) в виде двухсимвольных кодов. Если этот параметр не указан, к ответу не применяются никакие ограничения. Например, чтобы ограничить регионы Германией и Францией, используйте следующий код:
```
    "includedRegionCodes": ["de", "fr"]
```
Если вы укажете и locationRestriction, и includedRegionCodes, результаты будут находиться в области пересечения двух настроек.

Примечание. Если использование кода страны приводит к непредвиденным результатам, убедитесь, что код включает нужные страны, зависимые территории и особые географические области. Коды можно найти в статье Википедии со списком кодов стран по ISO 3166 и на онлайн-платформе ISO.
inputOffset

Смещение символа Юникода, начинающееся с нуля, которое указывает на позицию курсора в input. Положение курсора может влиять на то, какие подсказки будут возвращены. Если поле пустое, по умолчанию используется длина input.

Примечание. В первом ограниченном предварительном выпуске это свойство называлось predictionTermOffset.
languageCode

Предпочтительный язык, на котором будут возвращены результаты. Результаты могут быть на разных языках, если язык, используемый в input, отличается от значения, указанного в languageCode, или если для возвращенного места нет перевода с местного языка на язык, указанный в languageCode.
- Чтобы указать предпочитаемый язык, используйте коды языка по стандарту IETF BCP-47.
- Если заголовок languageCode не указан, API использует значение, заданное в заголовке Accept-Language. Если ни один из них не указан, по умолчанию используется значение en. Если вы укажете недопустимый код языка, API вернет ошибку INVALID_ARGUMENT.
- Предпочтительный язык незначительно влияет на набор результатов, возвращаемых API, и порядок их следования. Это также влияет на способность API исправлять орфографические ошибки.
- Формат подсказок мест зависит от того, что пользователь вводит в запросе.
  - Сначала выбираются подходящие термины в параметре input, используя названия, соответствующие языковым настройкам, указанным в параметре languageCode (если он доступен), а в противном случае – названия, наиболее подходящие к запросу пользователя.
  - Названия мест могут быть отформатированы с использованием альтернативных названий, чтобы соответствовать терминам в параметре input, включая названия на языках, отличных от языка, указанного в параметре languageCode.
  - Почтовые адреса форматируются на местном языке, по возможности с использованием письменности, понятной пользователю, и только после того, как будут выбраны термины, соответствующие терминам в параметре input.
  - Все остальные адреса возвращаются на предпочитаемом языке после того, как будут выбраны соответствующие термины, совпадающие с терминами в параметре input. Если название на выбранном языке недоступно, API использует наиболее близкое соответствие.
locationBias или locationRestriction

Чтобы задать область поиска, можно указать параметр locationBias или locationRestriction, но не оба одновременно. Параметр locationRestriction указывает регион, в котором должны находиться результаты, а параметр locationBias – регион, рядом с которым должны находиться результаты, но они могут быть и за его пределами.

Примечание. Если вы не укажете ни locationBias, ни locationRestriction, функция "Автозаполнение (новая версия)" по умолчанию будет использовать смещение на основе IP-адреса. При использовании функции "Смещение по IP" в автозаполнении (новая версия) результаты смещаются на основе IP-адреса устройства.
- locationBias
  
  Определяет область поиска. Это местоположение используется в качестве предпочтения, то есть могут быть возвращены результаты, находящиеся рядом с указанным местоположением, в том числе за пределами заданной области.
- locationRestriction
  
  Указывает область поиска. Результаты за пределами указанной области не возвращаются.
Укажите регион locationBias или locationRestriction в виде прямоугольной области просмотра или круга.
- Круг определяется центральной точкой и радиусом в метрах. Радиус должен быть в диапазоне от 0,0 до 50 000,0 включительно. Значение по умолчанию – 0.0. Для locationRestriction необходимо задать радиус больше 0.0. В противном случае запрос не вернет результатов.
  
  Пример:
```
"locationBias": {
  "circle": {
    "center": {
      "latitude": 37.7937,
      "longitude": -122.3965
    },
    "radius": 500.0
  }
}
```
- Прямоугольник – это область просмотра с координатами широты и долготы, представленная двумя диагонально противоположными точками low и high. Область просмотра считается замкнутой, то есть включает в себя границы. Широта должна находиться в диапазоне от -90 до +90 градусов включительно, а долгота – в диапазоне от -180 до +180 градусов включительно:
  - Если low = high, область просмотра состоит из одной точки.
  - Если low.longitude > high.longitude, диапазон долготы инвертируется (область просмотра пересекает линию долготы 180 градусов).
  - Если low.longitude = -180 градусов, а high.longitude = 180 градусов, область просмотра включает все долготы.
  - Если low.longitude = 180 градусов, а high.longitude = -180 градусов, диапазон долготы будет пустым.
  Поля low и high должны быть заполнены, а представляемый ими прямоугольник не может быть пустым. Если область просмотра пуста, возникает ошибка.
  
  Например, эта область просмотра полностью охватывает Нью-Йорк:
```
"locationBias": {
  "rectangle": {
    "low": {
      "latitude": 40.477398,
      "longitude": -74.259087
    },
    "high": {
      "latitude": 40.91618,
      "longitude": -73.70018
    }
  }
}
```
происхождение

Начальная точка, от которой рассчитывается расстояние по прямой до пункта назначения (возвращается как distanceMeters). Если это значение не указано, расстояние по прямой не возвращается. Должны быть указаны координаты широты и долготы:
```
"origin": {
    "latitude": 40.477398,
    "longitude": -74.259087
}
```
regionCode

Код региона, используемый для форматирования ответа, в виде двухсимвольного значения национального домена верхнего уровня. Большинство кодов ccTLD совпадают с кодами ISO 3166-1, однако имеются некоторые исключения. Например, ccTLD Великобритании – uk (.co.uk), а код ISO 3166-1 – gb (технически для "Соединенного Королевства Великобритании и Северной Ирландии").

Предложения также могут быть смещены в зависимости от кодов регионов. Google рекомендует задавать параметр regionCode в соответствии с региональными настройками пользователя.

Если вы укажете недействительный код региона, API вернет ошибку INVALID_ARGUMENT. Параметр может влиять на результаты в соответствии с действующим законодательством.
sessionToken

Токены сеансов – это создаваемые пользователем строки, которые отслеживают вызовы Autocomplete (New) как "сеансы". Новая версия Autocomplete использует токены сеансов, чтобы сгруппировать этапы запроса и выбора выполняемого пользователем поиска с функцией автозаполнения в отдельный сеанс для выставления счетов. Подробнее о токенах сеансов…

Выберите параметры, чтобы сместить результаты

Параметры автозаполнения (новые) могут по-разному влиять на результаты поиска. В таблице ниже приведены рекомендации по использованию параметров в зависимости от желаемого результата.

Параметр	Рекомендация по использованию
`regionCode`	Задается в соответствии с региональными настройками пользователя.
`includedRegionCodes`	Ограничивает результаты поиска списком указанных регионов.
`locationBias`	Используйте, если нужно получить результаты в определенном регионе или рядом с ним. Если применимо, определите регион как область просмотра карты, которую видит пользователь.
`locationRestriction`	Используйте параметр only, если результаты за пределами региона не должны возвращаться.
`origin`	Используйте, когда нужно указать расстояние по прямой до каждого прогноза. Примечание. Расстояние будет доступно не для каждого прогноза. Подробнее о том, почему в ответе нет расстояния…

Примеры использования Autocomplete (новой версии)

Как ограничить область поиска с помощью параметра locationRestriction

Примечание. В Autocomplete (New) по умолчанию используется смещение по IP-адресу, чтобы контролировать область поиска. При использовании функции "Смещение по IP-адресу" сервис "Автозаполнение (новая версия)" учитывает IP-адрес устройства, чтобы показывать более релевантные результаты. Вы можете указать область поиска, используя locationRestriction или locationBias, но не оба символа одновременно.

locationRestriction – определяет область поиска. Результаты за пределами указанной области не возвращаются. В примере ниже метод locationRestriction используется для ограничения запроса окружностью радиусом 5000 метров с центром в Сан-Франциско.

curl -X POST -d '{
  "input": "Art museum",
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

Все результаты из указанных областей содержатся в массиве suggestions:

  {
    "suggestions": [
      {
        "placePrediction": {
          "place": "places/ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "placeId": "ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "text": {
            "text": "Asian Art Museum, Larkin Street, San Francisco, CA, USA",
            "matches": [
              {
                "startOffset": 6,
                "endOffset": 16
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Asian Art Museum",
              "matches": [
                {
                  "startOffset": 6,
                  "endOffset": 16
                }
              ]
            },
            "secondaryText": {
              "text": "Larkin Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "establishment",
            "museum",
            "point_of_interest"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJI7NivpmAhYARSuRPlbbn_2w",
          "placeId": "ChIJI7NivpmAhYARSuRPlbbn_2w",
          "text": {
            "text": "de Young Museum, Hagiwara Tea Garden Drive, San Francisco, CA, USA",
            "matches": [
              {
                "endOffset": 15
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "de Young Museum",
              "matches": [
                {
                  "endOffset": 15
                }
              ]
            },
            "secondaryText": {
              "text": "Hagiwara Tea Garden Drive, San Francisco, CA, USA"
            }
          },
          "types": [
            "establishment",
            "point_of_interest",
            "tourist_attraction",
            "museum"
          ]
        }
      },
      /.../
    ]
  }

Вы также можете использовать locationRestriction, чтобы ограничить поиск прямоугольной областью просмотра. В следующем примере запрос ограничен центром Сан-Франциско:

  curl -X POST -d '{
    "input": "Art museum",
    "locationRestriction": {
      "rectangle": {
        "low": {
          "latitude": 37.7751,
          "longitude": -122.4219
        },
        "high": {
          "latitude": 37.7955,
          "longitude": -122.3937
        }
      }
    }
  }' \
  -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
  https://places.googleapis.com/v1/places:autocomplete

Результаты содержатся в массиве suggestions:

  {
    "suggestions": [
      {
        "placePrediction": {
          "place": "places/ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "placeId": "ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "text": {
            "text": "Asian Art Museum, Larkin Street, San Francisco, CA, USA",
            "matches": [
              {
                "startOffset": 6,
                "endOffset": 16
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Asian Art Museum",
              "matches": [
                {
                  "startOffset": 6,
                  "endOffset": 16
                }
              ]
            },
            "secondaryText": {
              "text": "Larkin Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "museum",
            "establishment"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJyQNK-4SAhYARO2DZaJleWRc",
          "placeId": "ChIJyQNK-4SAhYARO2DZaJleWRc",
          "text": {
            "text": "International Art Museum of America, Market Street, San Francisco, CA, USA",
            "matches": [
              {
                "startOffset": 14,
                "endOffset": 24
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "International Art Museum of America",
              "matches": [
                {
                  "startOffset": 14,
                  "endOffset": 24
                }
              ]
            },
            "secondaryText": {
              "text": "Market Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "museum",
            "point_of_interest",
            "tourist_attraction",
            "art_gallery",
            "establishment"
          ]
        }
      }
    ]
  }

Как использовать предпочтения для результатов поиска в определенной области с помощью locationBias

При использовании locationBias местоположение служит смещением, то есть могут возвращаться результаты в указанном местоположении, в том числе за пределами указанной области. В следующем примере запрос смещен в сторону центра Сан-Франциско:

curl -X POST -d '{
  "input": "Amoeba",
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

Теперь в результатах поиска гораздо больше объектов, в том числе находящихся за пределами радиуса 5000 метров:

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Haight Street, San Francisco, CA, USA"
          }
        },
        "types": [
          "electronics_store",
          "point_of_interest",
          "store",
          "establishment",
          "home_goods_store"
        ]
      }
    },
    {
      "placePrediction": {
        "place": "places/ChIJr7uwwy58hYARBY-e7-QVwqw",
        "placeId": "ChIJr7uwwy58hYARBY-e7-QVwqw",
        "text": {
          "text": "Amoeba Music, Telegraph Avenue, Berkeley, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Telegraph Avenue, Berkeley, CA, USA"
          }
        },
        "types": [
          "electronics_store",
          "point_of_interest",
          "establishment",
          "home_goods_store",
          "store"
        ]
      }
    },
    ...
  ]
}

Вы также можете использовать параметр locationBias, чтобы задать приоритет поиска в прямоугольной области просмотра. В следующем примере запрос ограничен центром Сан-Франциско:

  curl -X POST -d '{
    "input": "Amoeba",
    "locationBias": {
      "rectangle": {
        "low": {
          "latitude": 37.7751,
          "longitude": -122.4219
        },
        "high": {
          "latitude": 37.7955,
          "longitude": -122.3937
        }
      }
    }
  }' \
  -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
  https://places.googleapis.com/v1/places:autocomplete

Хотя результаты поиска в прямоугольной области просмотра появляются в ответе, некоторые результаты находятся за пределами заданных границ из-за смещения. Результаты также содержатся в массиве suggestions:

  {
    "suggestions": [
      {
        "placePrediction": {
          "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
          "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
          "text": {
            "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Amoeba Music",
              "matches": [
                {
                  "endOffset": 6
                }
              ]
            },
            "secondaryText": {
              "text": "Haight Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "store",
            "establishment"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJr7uwwy58hYARBY-e7-QVwqw",
          "placeId": "ChIJr7uwwy58hYARBY-e7-QVwqw",
          "text": {
            "text": "Amoeba Music, Telegraph Avenue, Berkeley, CA, USA",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Amoeba Music",
              "matches": [
                {
                  "endOffset": 6
                }
              ]
            },
            "secondaryText": {
              "text": "Telegraph Avenue, Berkeley, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "store",
            "establishment"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJRdmfADq_woARYaVhnfQSUTI",
          "placeId": "ChIJRdmfADq_woARYaVhnfQSUTI",
          "text": {
            "text": "Amoeba Music, Hollywood Boulevard, Los Angeles, CA, USA",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Amoeba Music",
              "matches": [
                {
                  "endOffset": 6
                }
              ]
            },
            "secondaryText": {
              "text": "Hollywood Boulevard, Los Angeles, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "store",
            "establishment"
          ]
        }
      },
    /.../
    ]
  }

Используйте includedPrimaryTypes

В параметре includedPrimaryTypes можно указать до пяти значений типов из таблицы А, таблицы Б, только (regions) или только (cities). Чтобы место было включено в ответ, его основной тип должен совпадать с одним из указанных значений.

В примере ниже в строке input указано значение Soccer, а параметр includedPrimaryTypes используется, чтобы ограничить результаты местами типа "sporting_goods_store".

curl -X POST -d '{
  "input": "Soccer",
  "includedPrimaryTypes": ["sporting_goods_store"],
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

Если вы не укажете параметр includedPrimaryTypes, то в результатах могут появиться заведения нежелательного типа, например "athletic_field".

Как запросить прогнозы запросов

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

curl -X POST -d '{
  "input": "Amoeba",
  "includeQueryPredictions": true,
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

Массив suggestions теперь содержит как подсказки мест, так и подсказки запросов, как показано выше в разделе Об ответе. Каждый прогноз запроса содержит поле text с рекомендованной строкой текстового поиска. Чтобы получить больше информации о любом из возвращенных вариантов запроса, можно отправить запрос текстового поиска (New).

Примечание. Подсказки не возвращаются, если задан параметр includedRegionCodes.

Использовать источник

В этом примере в запрос включены координаты широты и долготы origin. Если вы добавите параметр origin, в ответе функции "Автозаполнение (новая версия)" появится поле distanceMeters, в котором будет указано расстояние по прямой от origin до пункта назначения. В этом примере начало координат устанавливается в центре Сан-Франциско:

curl -X POST -d '{
  "input": "Amoeba",
  "origin": {
    "latitude": 37.7749,
    "longitude": -122.4194
  },
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

Теперь ответ содержит distanceMeters:

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Haight Street, San Francisco, CA, USA"
          }
        },
        "types": [
          "home_goods_store",
          "establishment",
          "point_of_interest",
          "store",
          "electronics_store"
        ],
        "distanceMeters": 3012
      }
    }
  ]
}

Как найти компании, которые откроются в будущем

В примере ниже показан запрос Autocomplete (New) для компаний, которые откроются в будущем в Нью-Медоусе, штат Айдахо:

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-d '{
  "input": "Roberts Greenhouse and Tree Farm",
  "includeFutureOpeningBusinesses": true,
  "locationBias": {
    "circle": {
      "center": {"latitude": 44.9755100, "longitude": -116.2842180},
      "radius": 20
    }
  }
}' \
"https://places.googleapis.com/v1/places:autocomplete"

В ответе есть информация о месте, но нет даты открытия.

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJp1-VoKWJplQRMz8g-7Wa3Do",
        "placeId": "ChIJp1-VoKWJplQRMz8g-7Wa3Do",
        "text": {
          "text": "Roberts Greenhouse and Tree Farm, McLain Street, New Meadows, ID, USA",
          "matches": [
            {
              "endOffset": 32
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Roberts Greenhouse and Tree Farm",
            "matches": [
              {
                "endOffset": 32
              }
            ]
          },
          "secondaryText": {
            "text": "McLain Street, New Meadows, ID, USA"
          }
        },
        "types": [
          "garden_center",
          "establishment",
          "service",
          "store",
          "point_of_interest"
        ]
      }
    }
  ]
}

В ответе не указано расстояние

В некоторых случаях distanceMeters отсутствует в теле ответа, даже если origin включен в запрос. Это может произойти в следующих случаях:

distanceMeters не учитывается в прогнозах route.
Параметр distanceMeters не включается, если его значение равно 0. Это происходит, когда прогнозируемое местоположение находится на расстоянии менее одного метра от указанного в параметре origin.

Клиентские библиотеки, пытающиеся прочитать поле distanceMeters из обработанного объекта, вернут поле со значением 0. Чтобы не вводить пользователей в заблуждение, не показывайте им нулевое расстояние.

Оптимизация функции автозаполнения (новая версия)

В этом разделе приведены рекомендации по эффективному использованию сервиса Autocomplete (New).

Рассмотрим некоторые общие рекомендации.

Чтобы быстро разработать пользовательский интерфейс, используйте виджет Autocomplete (New) Maps JavaScript API, виджет Autocomplete (New) Places SDK для Android или виджет Autocomplete (New) Places SDK для iOS.
В первую очередь ознакомьтесь с самыми важными полями данных Autocomplete (New).
Поля с предпочтениями и ограничениями местоположений использовать не обязательно, но они могут значительно повлиять на производительность функции автозаполнения.
Используйте обработку ошибок в приложении на случай, если API вернет ошибку.
Убедитесь, что приложение сможет обработать тот случай, если пользователь не выберет место, и предложить вариант продолжения работы.

Да, нужно больше сведений

Используйте сервис Autocomplete (New) на основе сеансов совместно с информацией о местах (New).
Поскольку вашему приложению требуются данные о месте (новая версия), например название места, статус компании или часы работы, в реализации автозаполнения (новой версии) следует использовать токен сеанса (программно или встроенный в виджеты JavaScript, Android или iOS) на сеанс, а также применимые коды Places в зависимости от того, какие поля с данными о месте вы запрашиваете.¹

Реализация виджета
Функция автоматического управления сеансами встроена в виджеты для JavaScript, Android, или iOS. В нее входят как новые запросы Autocomplete, так и новый запрос информации о местах для выбранной подсказки. Обязательно укажите параметр fields, чтобы запрашивались только нужные поля данных Autocomplete (New).

Программная реализация
Используйте токен сеанса с запросами Autocomplete (New). При запросе информации о местах (New) по выбранной подсказке укажите следующие параметры:

идентификатор места из ответа Autocomplete (новая версия);
токен сеанса, использованный в запросе Autocomplete (New);
параметр fields, указывающий нужные поля данных для функции "Автозаполнение (новая версия)".

Нет, нужны только адрес и местоположение

Возможно, для вашего приложения Geocoding API будет более выгодным вариантом, чем информация о местах (New). Это зависит от того, насколько эффективно вы используете Autocomplete (New). Эффективность функции автозаполнения (новой) в каждом приложении зависит от того, какие запросы вводят пользователи, где используется приложение и реализованы ли рекомендации по оптимизации производительности.

Чтобы ответить на приведенный ниже вопрос, проанализируйте, сколько символов в среднем вводит пользователь, прежде чем выбирать подсказку Autocomplete (New) в приложении.

Выбирают ли пользователи подсказку Autocomplete (New) в среднем из числа первых четырех запросов?

Да

Реализуйте Autocomplete (New) программно без токенов сеансов и вызывайте Geocoding API для выбранной подсказки места.
Geocoding API предоставляет адреса и координаты широты и долготы. Четыре запроса Autocomplete и вызов Geocoding API о выбранной подсказке места стоят меньше, чем сеанс Autocomplete (New)¹.

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

Нет

Используйте сервис Autocomplete (New) на основе сеансов совместно с информацией о местах (New).
Поскольку среднее количество запросов, которые вы ожидаете сделать до того, как пользователь выберет подсказку Autocomplete (New), превышает стоимость тарифа за сеанс, в вашей реализации Autocomplete (New) должен использоваться токен сеанса как для запросов Autocomplete (New), так и для связанного запроса информации о местах (New) за сеанс. ¹

Реализация виджета
Функция автоматического управления сеансами встроена в виджеты для JavaScript, Android и iOS. В нее входят как новые запросы Autocomplete, так и новый запрос информации о местах для выбранной подсказки. Обязательно укажите параметр fields, чтобы запрашивались только нужные поля.

Программная реализация
Используйте токен сеанса с запросами новой версии функции автозаполнения. При запросе информации о местах (New) по выбранной подсказке включите следующие параметры:

идентификатор места из ответа Autocomplete (New);
токен сеанса, использованный в запросе Autocomplete (New);
Параметр fields, указывающий поля, например адрес и геометрические данные.

Рассмотрите возможность откладывать запросы Autocomplete (New)
Вы можете попробовать различные стратегии, например откладывать запрос Autocomplete (New), пока пользователь не введет первые три или четыре символа, чтобы ваше приложение совершало меньше запросов. Например, если вы отправляете запросы Autocomplete (New) для каждого символа после того, как пользователь ввел третий символ, то при вводе семи символов и выборе подсказки, для которой вы отправляете один запрос Geocoding API, общая стоимость будет складываться из стоимости четырех запросов Autocomplete (New) Per Request и одного запроса Geocoding.¹

Если при откладывании запросов среднее число программных запросов станет меньше четырех, вы сможете эффективно использовать сервис Autocomplete (New) с Geocoding API. Обратите внимание, что пользователь, ожидающий появления подсказок с каждым введенным символом, может принять откладывание запросов за задержку.

Вы можете применить рекомендации по оптимизации эффективности, чтобы помочь пользователям получать нужные результаты, вводя меньше символов.

Информацию о стоимости можно найти в списках цен на платформу Google Карт.

Смещение местоположения

Настроить предпочтение результатов из определенной области, передав параметры location и radius. Это означает, что Autocomplete (New) будет предпочитать показывать результаты в заданной области. однако более отдаленные точки также могут быть включены в ответ. Вы можете использовать параметр includedRegionCodes, чтобы отфильтровать результаты и показать только места в указанной стране.

Предупреждение. Если параметр radius не указан, параметр location игнорируется.

Результаты поиска организаций обычно не занимают высокие позиции, если область поиска большая. Если вы хотите, чтобы заведения появлялись в результатах поиска вместе с геокодами, задайте меньший радиус. Также можно использовать types=establishment, чтобы ограничить результаты только заведениями.

Ограничение местоположений

Ограничить результаты определенной областью, передав параметр locationRestriction.

Вы также можете ограничить результаты регионом, заданным параметрами location и radius, добавив параметр locationRestriction. Это означает, что функция автозаполнения (новая версия) должна возвращать только результаты в пределах этого региона.

Попробовать

В API Explorer можно отправлять примеры запросов, чтобы ознакомиться с API и его возможностями.

Нажмите на значок API api в правой части страницы.
При необходимости измените параметры запроса.
Нажмите кнопку Выполнить. В диалоговом окне выберите аккаунт, который хотите использовать для запроса.
На панели APIs Explorer нажмите на значок полноэкранного режима , чтобы развернуть окно APIs Explorer.

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

Введение

Запросы к Autocomplete API (новая версия)

Поддерживаемые параметры

Об ответе

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

ввод

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

FieldMask

includeFutureOpeningBusinesses

includedPrimaryTypes

includePureServiceAreaBusinesses

includeQueryPredictions

includedRegionCodes

inputOffset

languageCode

locationBias или locationRestriction

locationBias

locationRestriction

происхождение

regionCode

sessionToken

Выберите параметры, чтобы сместить результаты

Примеры использования Autocomplete (новой версии)

Как ограничить область поиска с помощью параметра locationRestriction

Как использовать предпочтения для результатов поиска в определенной области с помощью locationBias

Используйте includedPrimaryTypes

Как запросить прогнозы запросов

Использовать источник

Как найти компании, которые откроются в будущем

В ответе не указано расстояние

Оптимизация функции автозаполнения (новая версия)

Рекомендации по оптимизации затрат

Базовая оптимизация затрат

Дополнительная оптимизация затрат

Да, нужно больше сведений

Нет, нужны только адрес и местоположение

Да

Нет

Рекомендации по повышению эффективности

Смещение местоположения

Ограничение местоположений

Попробовать

Autocomplete (New)