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

Введение

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

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

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

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

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

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

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

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

Полный 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
            }]
        },
        ...
    }
  ...]
}

Необходимые параметры

• вход

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

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

• 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: *

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

  Заведение может иметь только один основной тип из типов, перечисленных в Таблице 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 , что означает, что ответ включает только предсказания места.

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

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

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

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

• inputOffset

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

• languageCode

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

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

• locationBias или locationRestriction

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

  • locationBias

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

  • locationRestriction

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

  Укажите область 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
  }

• regionCode

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

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

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

• sessionToken

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

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

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

Ограничьте поиск определенной областью, используя 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 поле, содержащее рекомендуемую строку поиска. Вы можете отправить запрос «Текстовый поиск (новый)» , чтобы получить дополнительную информацию о любом из возвращенных предсказаний запроса.

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

В этом примере укажите в запросе координаты 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
      }
    }
  ]
}

Расстояние отсутствует в ответе

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

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

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

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

В этом разделе описаны лучшие практики, которые помогут вам максимально эффективно использовать сервис автозаполнения (новый).

Вот несколько общих рекомендаций:

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

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

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

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

Расширенная оптимизация затрат

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

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

Требует ли ваше приложение какой-либо дополнительной информации, помимо адреса и широты/долготы выбранного прогноза?

лучшие практики повышения производительности

В следующих рекомендациях описаны способы оптимизации работы функции автозаполнения (нового кода):

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

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

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

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

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

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

Попробуйте!

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

1. Выберите значок API в правой части страницы.

2. При желании можно отредактировать параметры запроса.

3. Нажмите кнопку «Выполнить» . В диалоговом окне выберите учетную запись, которую вы хотите использовать для выполнения запроса.

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