Автозаполнение (новое)

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

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

Служба автозаполнения (новая) может сопоставлять полные слова и подстроки входных данных, распознавая названия мест, адреса и коды плюсов . Таким образом, приложения могут отправлять запросы по мере ввода пользователем, чтобы оперативно предоставлять прогнозы по местоположению и запросам.

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

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

Например, вы вызываете API, используя в качестве входных данных строку, содержащую частичный пользовательский ввод «Сицилийский пиз», с областью поиска, ограниченной Сан-Франциско, Калифорния. Затем ответ содержит список подсказок мест , соответствующих строке поиска и области поиска, например ресторан под названием «Sicilian Pizza Kitchen», а также подробную информацию об этом месте.

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

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

Примечание. Вы можете использовать автозаполнение (новое) даже без карты. Если вы показываете карту, это должна быть карта Google. Когда вы отображаете подсказки от службы автозаполнения (новая) без карты, вы должны включить логотип Google, отображаемый в поле поиска/результатах. Дополнительную информацию см. в разделе «Отображение логотипа Google и сведений об авторстве» .

API Explorer позволяет вам делать запросы в реальном времени, чтобы вы могли ознакомиться с API и опциями 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

Об ответе

Автозаполнение (новое) возвращает объект JSON в качестве ответа. В ответ:

• Массив suggestions содержит все прогнозируемые места и запросы в порядке их предполагаемой релевантности. Каждое место представлено полем placePrediction , а каждый запрос представлен полем queryPrediction .
• Поле placePrediction содержит подробную информацию об одном предсказании места, включая идентификатор места и текстовое описание.
• Поле queryPrediction содержит подробную информацию о прогнозе одного запроса.

Примечание. Автозаполнение (новое) возвращает пять подсказок в общей сложности в виде 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
            }]
        },
        ...
    }
  ...]
}

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

• вход

  Текстовая строка, по которой осуществляется поиск. Укажите полные слова и подстроки, географические названия, адреса и плюсовые коды . Служба автозаполнения (новая) возвращает совпадения кандидатов на основе этой строки и упорядочивает результаты на основе их предполагаемой релевантности.

Дополнительные параметры

• Маска поля

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

  Укажите разделенный запятыми список предлагаемых полей для возврата. Например, чтобы получить suggestions.placePrediction.place и suggestions.placePrediction.text предложения.

    X-Goog-FieldMask: places.displayName,places.formattedAddress

  Примечание. Пробелы в списке полей не допускаются.

  Используйте * , чтобы получить все поля.

    X-Goog-FieldMask: *

  Подстановочный знак «*» выбирает все поля.

• включенные первичные типы

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

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

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

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

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

  • Указано более пяти типов.
  • Помимо (cities) или (regions) указывается любой тип.
  • Указываются любые нераспознанные типы.
  Примечание. Параметр includedPrimaryTypes работает только с основным типом места, а не со всеми типами, связанными с этим местом. Хотя у каждого места есть основной тип, не каждый основной тип поддерживается Places API (новый). Поддерживаемые типы включают те, которые перечислены в Таблице A или Таблице B.

• includeQueryPredictions

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

• включенные коды регионов

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

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

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

• inputOffset

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

  Примечание. В первоначальной версии Private Preview это свойство называлось predictionTermOffset .

• языковой код

  Предпочитаемый язык для возврата результатов. Результаты могут быть на смешанных языках, если язык, используемый во input отличается от значения, указанного в languageCode , или если возвращаемое место не имеет перевода с локального языка на languageCode .

  • Для указания предпочтительного языка необходимо использовать языковые коды IETF BCP-47 .
  • Если languageCode не указан, API использует значение, указанное в заголовке Accept-Language . Если ни один из них не указан, по умолчанию используется en . Если вы укажете неверный код языка, API вернет ошибку INVALID_ARGUMENT .
  • Предпочитаемый язык оказывает небольшое влияние на набор результатов, которые API выбирает для возврата, и порядок их возврата. Это также влияет на способность API исправлять орфографические ошибки.
  • API пытается предоставить почтовый адрес, который будет доступен для чтения как пользователю, так и местному населению, и в то же время отражает вводимые пользователем данные. Подсказки мест форматируются по-разному в зависимости от вводимых пользователем данных в каждом запросе.
    • Соответствующие термины во input параметре выбираются первыми, используя имена, соответствующие языковым предпочтениям, указанным в параметре languageCode , если он доступен, а в противном случае используются имена, которые лучше всего соответствуют вводу пользователя.
    • Уличные адреса форматируются на местном языке, в сценарии, который может быть читаем пользователем, если это возможно, только после того, как соответствующие термины будут выбраны в соответствии с терминами во input параметре.
    • Все остальные адреса возвращаются на предпочитаемом языке после того, как соответствующие термины были выбраны для соответствия терминам во input параметре. Если имя недоступно на предпочитаемом языке, API использует наиболее близкое совпадение.

• предвзятость местоположения или ограничение местоположения

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

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

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

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

  • МестоположениеОграничение

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

  Укажите область locationBias или locationRestriction в виде прямоугольного видового экрана или круга.

  • Круг определяется центральной точкой и радиусом в метрах. Радиус должен находиться в диапазоне от 0,0 до 50000,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
  }

• Код региона

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

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

• сессионный токен

  Токены сеанса — это созданные пользователем строки, которые отслеживают вызовы автозаполнения (новые) как «сеансы». Автозаполнение (новое) использует токены сеанса для группировки этапов запроса и выбора пользовательского поиска с автозаполнением в отдельный сеанс для целей выставления счетов. Дополнительные сведения см. в разделе Токены сеанса .

Примеры автозаполнения (новые)

Используйте locationRestriction и locationBias

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

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

curl -X POST -d '{
  "input": "Amoeba",
  "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/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",
          "store",
          "point_of_interest",
          "electronics_store"
        ]
      }
    }
  ]
}

При использовании 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"
        ]
      }
    },
    ...
  ]
}

Используйте включенные первичные типы

Используйте параметр includedPrimaryTypes , чтобы указать до пяти значений типа из Table A , Table B , only (regions) или only (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 поле, содержащее рекомендуемую строку текстового поиска. Вы можете сделать запрос на текстовый поиск (новый), чтобы получить дополнительную информацию о любом из возвращаемых прогнозов запроса.

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

Использовать происхождение

В этом примере включите в запрос origin как координаты широты и долготы. Когда вы включаете origin , API включает в ответ поле 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
      }
    }
  ]
}

Попробуйте!

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

1. Выберите значок API, , в правой части страницы.
2. При необходимости разверните Показать стандартные параметры и установите для параметра fields маску поля .
3. При желании отредактируйте тело запроса .
4. Нажмите кнопку «Выполнить» . Во всплывающем окне выберите учетную запись, которую вы хотите использовать для отправки запроса.

5. На панели API Explorer выберите значок развертывания, , чтобы развернуть окно API Explorer.