Методы GeocodeAddress и SearchDestinations поддерживают необязательный параметр effort, который позволяет найти баланс между задержкой ответа и точностью разрешения адреса.
Стандартное геокодирование обрабатывает правильно отформатированные почтовые адреса менее чем за секунду, но реальные входные данные часто бывают неполными, неформальными или сложными (например, "Flat 4B, Sunrise Apartments, opposite Central Mall, Andheri West,
Mumbai" или "where the warriors play, sf"). Настроив более высокий уровень effort, вы можете указать Geocoding API применять расширенное обоснование и устранение неоднозначности для разрешения сложных адресов.
Уровни усилий
Укажите одно из следующих значений параметра effort:
| Уровень усилий | Описание | Стандартная задержка | Рекомендуемые варианты использования |
|---|---|---|---|
EFFORT_UNSPECIFIED |
Значение по умолчанию. Работает так же, как и LOW. |
Доли секунды | Стандартное геокодирование по умолчанию. |
LOW |
Оптимизирована для максимально быстрого ответа. Не выполняет расширенный поиск и не устраняет неоднозначность для сложных адресов. | Доли секунды | Интерактивный поиск в реальном времени, стандартная проверка адресов в больших объемах. |
MEDIUM |
Баланс между скоростью и точностью. Большинство запросов возвращаются со стандартной низкой задержкой. Для неоднозначных или сложных адресов сервис применяет дополнительную обработку, чтобы повысить точность. Это может занять до нескольких секунд. | Менее секунды для стандартных адресов; до нескольких секунд (≤ 4 секунд) для неоднозначных адресов. | Интерактивные рабочие процессы пользователей (например, подтверждение адреса при оформлении заказа), в которых пользователи могут выдержать короткую паузу. |
HIGH |
Максимально повышает точность распознавания неполных, неформальных или сложных адресов. Время ответа может быть значительно больше. | До 20 секунд для сложных адресов. | Фоновая обработка, пакетное геокодирование, диспетчеризация логистики или асинхронное уточнение адреса после оформления заказа. |
Примеры запросов
Поиск пунктов назначения (SearchDestinations)
Включите поле effort в тело запроса JSON POST к https://geocode.googleapis.com/v4alpha/geocode/destinations. Параметр effort в основном влияет на разрешение addressQuery:
curl -X POST -d '{
"addressQuery": {
"addressQuery": "Flat 4B, Sunrise Apartments, opposite Central Mall, Andheri West, Mumbai"
},
"effort": "HIGH"
}' \
-H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4alpha/geocode/destinations
Геокодирование адреса (GeocodeAddress)
Передайте параметр effort в качестве параметра запроса URL в запросе GET к конечной точке /v4alpha/:
curl -X GET -H 'Content-Type: application/json' \ -H "X-Goog-Api-Key: API_KEY" \ "https://geocode.googleapis.com/v4alpha/geocode/address/where+the+warriors+play,+sf?effort=MEDIUM"
Как уменьшить влияние задержки
Если вы используете в приложении режим MEDIUM или HIGH, то проще всего отправлять однопроходные запросы. Однако в этих режимах запросы могут выполняться с большей задержкой, что может замедлить синхронные, пользовательские и чувствительные к задержкам рабочие процессы.
Чтобы уменьшить влияние задержки на интерактивные пути пользователя (например, оформление заказа или бронирование), можно использовать многоэтапный рабочий процесс:
- Проход 1 (интерактивный). Отправьте синхронный запрос с
effort=LOW(или по умолчанию), чтобы немедленно проверить адрес с задержкой менее секунды. - Этап 2 (фоновый). Отправьте асинхронный последующий запрос с помощью
effort=MEDIUMилиeffort=HIGH(например, после оформления заказа или перед отправкой), чтобы преобразовать сложные адреса в высокоточные координаты, входы и точки навигации, не блокируя пользователя.
Лимиты на использование
На этапе экспериментального запуска (v4alpha) для запросов, в которых параметр effort имеет значение MEDIUM или HIGH, действуют более строгие ограничения частоты запросов, чем для стандартных запросов (LOW). Если ваше приложение превысит эти ограничения частоты запросов, API вернет ошибку RESOURCE_EXHAUSTED (HTTP 429). Если вы столкнулись с ошибками HTTP 429 или вам нужна более высокая квота, свяжитесь с нами через канал обратной связи.
Как оставить отзыв
Это экспериментальная функция Geocoding API. Мы будем рады получить ваши отзывы по адресу geocoding-feedback-channel@google.com.