Autocomplete (New)

Выберите платформу: Android iOS JavaScript Веб-сервисы
Разработчики из Европейской экономической зоны (ЕЭЗ)

Введение

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

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

Ответ от нового сервиса Autocomplete может содержать два типа подсказок:

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

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

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

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

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

Запросы к Autocomplete (New)

Запрос Autocomplete (New) – это 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

Смещение символа Юникода от нуля для позиции курсора в строке ввода, влияющее на подсказки. Значение по умолчанию – длина входных данных.

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 и адреса в результатах запроса сведений о месте для того же идентификатора места.
    • В этом случае альтернативные названия некоторых мест могут быть на языке, отличном от указанного в параметре languageCode, в зависимости от того, какие названия точнее соответствуют запросу пользователя.
  • Поле queryPrediction содержит подробную информацию об одной подсказке.

Полный объект 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. На основе этой строки сервис Autocomplete (New) возвращает список подходящих мест, упорядоченных по их предполагаемой релевантности.

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

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

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

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

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

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

Запрос отклоняется с ошибкой INVALID_REQUEST, если:

  • указано более пяти типов;
  • указать любой тип в дополнение к (cities) или (regions);
  • указать неизвестный тип;

includePureServiceAreaBusinesses

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

includeQueryPredictions

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

includedRegionCodes

Включать только результаты из указанных регионов. Регионы задаются в виде массива, содержащего до 15 двухсимвольных значений ccTLD («национального домена верхнего уровня»). Если этот параметр не указан, к ответу не применяются никакие ограничения. Например, чтобы ограничить регионы Германией и Францией, используйте следующий код:

    "includedRegionCodes": ["de", "fr"]

Если вы укажете и locationRestriction, и includedRegionCodes, то результаты будут находиться в области пересечения двух настроек.

inputOffset

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

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

    Определяет область поиска. Результаты за пределами указанной области не возвращаются.

Укажите регион 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 и верхней точкой. Область просмотра считается замкнутым регионом, то есть включает в себя свою границу. Широта должна находиться в диапазоне от -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 (домен верхнего уровня). Большинство кодов ccTLD совпадают с кодами ISO 3166-1, однако имеются некоторые исключения. Например, ccTLD Великобритании – uk (.co.uk), а код ISO 3166-1 – gb (технически для Соединенного Королевства Великобритании и Северной Ирландии).

Кроме того, на подсказки влияют коды регионов. Google рекомендует задавать значение regionCode в соответствии с региональными настройками пользователя.

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

Если задать параметр regionCode, в подсказках для этого региона может не быть названия страны, то есть structuredFormat.secondaryText может отсутствовать. Поэтому убедитесь, что ваше приложение обрабатывает случаи, когда secondaryText не определен или отсутствует.

sessionToken

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

Выберите параметры для смещения результатов

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

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

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

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 можно указать до пяти значений из таблицы A, таблицы B, только (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).

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

В этом примере в запрос включены координаты широты и долготы origin. Если вы включите origin, Autocomplete (New) добавит в ответ поле 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, что соответствует прогнозам, которые находятся на расстоянии менее 1 метра от указанного местоположения origin.

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

Оптимизация Autocomplete (New)

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

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

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

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

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

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

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

Рассмотрите возможность программно реализовать сервис Autocomplete (New), чтобы получить доступ к тарифу SKU: Autocomplete Request и запрашивать результаты Geocoding API о выбранном месте вместо информации о местах (New). Тариф Per Request в сочетании Geocoding API будет выгоднее, чем тариф Per Session (на основе сеансов), если соблюдаются два следующих условия:

  • Если вам нужны только широта и долгота или адрес выбранного пользователем места, получить эту информацию с помощью Geocoding API дешевле, чем вызывать Place Details (New).
  • Если пользователи выбирают подсказку функции автозаполнения в среднем из первых четырех запросов подсказок Autocomplete (New) или из меньшего числа, тариф Per Request может быть выгоднее, чем Per Session.
Чтобы выбрать реализацию Autocomplete (New), которая будет наиболее экономичной для вашего приложения, найдите в таблице ниже строку, соответствующую потребностям вашего приложения.
Что нужно для подачи заявки Среднее количество запросов Autocomplete (New), прежде чем пользователь выберет подсказку Рекомендуемые решения
Информация о месте, кроме адреса и местоположения, например название, статус компании или часы работы. Не ограничено Автозаполнение на основе сеансов (новое) с информацией о местах (новое)
Только адрес и широта и долгота выбранной подсказки Четыре или меньше Автозаполнение (новая версия) с оплатой за запрос и Geocoding API
Только адрес и широта и долгота выбранной подсказки Больше четырех Autocomplete (New) на основе сеансов для приложений, работающих только с адресами

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

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

Автозаполнение (Новое) на основе сеансов с информацией о местах (Новое)

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

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

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

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

Оплата за запрос Autocomplete (New) с Geocoding API

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

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

Autocomplete (New) на основе сеансов для приложений, работающих только с адресами

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

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

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

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

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

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

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

  1. Цены указаны в прейскурантах платформы Google Карт.

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

В рекомендациях ниже описаны способы оптимизации производительности Autocomplete (New):

  • Добавьте в свою реализацию Autocomplete (New) ограничения для отдельных стран, смещение местоположения и (для автоматизированных реализаций) языковые настройки. Предпочитаемый язык не нужен в случае виджетов, потому что для них язык определяется на основе языковых настроек браузера или мобильного устройства.
  • Если вместе с Autocomplete (New) отображается карта, вы можете сделать предпочитаемым местоположением видимую область карты.
  • Если пользователь не выберет ни одну из подсказок Autocomplete (New) – чаще всего такое бывает, если ни одна из них не соответствует искомому адресу, — вы можете повторно использовать изначально введенные пользователем данные, чтобы получить более подходящие результаты:
    • Если вы рассчитываете, что пользователь будет вводить только информацию об адресе, повторно используйте изначально введенные им данные в вызове Geocoding API.
    • Если пользователь скорее всего будет вводить запросы для определенного места по названию или адресу, используйте запрос информации о местах (New). Если ожидается, что результаты будут из определенного региона, используйте предпочтение местоположений.
    К другим сценариям, при которых лучше вернуться к использованию Geocoding API, относятся следующие:
    • Пользователи вводят адреса, содержащие номер квартиры или офиса. Так, для адреса в Чехии "Stroupežnického 3191/17, Praha" Autocomplete (New) покажет частичную подсказку.
    • Пользователь вводит адрес с префиксом для ряда домов, например "23-30 29th St, Queens" в Нью-Йорке или "47-380 Kamehameha Hwy, Kaneohe" на острове Кауаи (Гавайи).

Привязка к местоположению

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

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

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

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

Попробовать

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

  1. Нажмите на значок API api в правой части страницы.

  2. При необходимости измените параметры запроса.

  3. Нажмите кнопку Execute (Выполнить). В диалоговом окне выберите аккаунт, который хотите использовать для отправки запроса.

  4. На панели API Explorer нажмите на значок полноэкранного режима fullscreen, чтобы развернуть окно API Explorer.