Эта страница переведена с помощью Cloud Translation API.

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

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

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

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

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

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

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

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

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

Запрос автозаполнения (новый) — это запрос 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

Сделайте запрос с помощью автозаполнения (новинка)

API Places поддерживает существующие API автозаполнения и автозаполнения запросов . Если вы знакомы с этими API, предварительная версия автозаполнения (новая) вносит следующие изменения:

Новое автозаполнение использует запросы HTTP POST. Передавайте параметры в теле запроса или в заголовках как часть запроса HTTP POST. Напротив, в существующих API параметры URL-адреса передаются с помощью HTTP-запроса GET.
Новое автозаполнение поддерживает как ключи API , так и токены OAuth в качестве механизма аутентификации.
В новом автозаполнении в качестве формата ответа поддерживается только JSON.

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

Текущий параметр	Новый параметр	Примечания
`components`	`includedRegionCodes`
`language`	`languageCode`
`location`	`locationBias`
`ipbias`		Если вы опустите и `locationBias` и `locationRestriction` , то API по умолчанию будет использовать смещение IP.
`offset`	`inputOffset`
`radius`	`locationBias` или `locationRestriction`
`region`	`regionCode`
`stricbounds`	`locationRestriction`
`sessiontoken`	`sessionToken`
`types`	`includedPrimaryTypes`

Ограничения использования

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

Варианты поддержки для предварительных выпусков

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

На предварительные версии не распространяется соглашение об уровне обслуживания платформы Google Карт .
Рекомендуется использовать резервные механизмы, особенно если вы используете предварительную версию в производственной среде. Некоторые примеры резервных ситуаций: превышение квоты, неожиданные коды ответов и задержка или неожиданные ответы по сравнению с существующим автозаполнением.

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

Если у вас возникнут другие вопросы о функциях, отправьте электронное письмо по адресу newplacesapi@google.com.

Об ответе

Автозаполнение (новое) возвращает объект 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
            }]
        },
        ...
    }
  ...]
}

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

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

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

включенные первичные типы
Место может иметь только один основной тип из связанных с ним типов Таблица A или Таблица B. Например, основным типом может быть "mexican_restaurant" или "steak_house" .
По умолчанию API возвращает все места на основе input параметра, независимо от значения основного типа, связанного с этим местом. Ограничьте результаты определенным основным типом или основными типами, передав параметр includedPrimaryTypes .
Используйте этот параметр, чтобы указать до пяти значений типа из таблицы A или таблицы B. Для включения в ответ место должно соответствовать одному из указанных значений основного типа.
Запрос отклоняется с ошибкой INVALID_REQUEST , если:
- Указано более пяти типов.
- Указываются любые нераспознанные типы.
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 , чтобы ограничить результаты запроса определенным типом, указанным в таблицах A и Table B. Вы можете указать массив, содержащий до пяти значений. Если этот параметр опущен, возвращаются все типы.

В следующем примере вы указываете 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
      }
    }
  ]
}

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

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

Сделайте запрос с помощью автозаполнения (новинка)

Ограничения использования

Варианты поддержки для предварительных выпусков

Об ответе

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

вход

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

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

includeQueryPredictions

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

inputOffset

языковой код

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

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

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

источник

Код региона

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

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

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

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

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

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