Автозаполнение по почтовому индексу в форме доставки

20 сентября 2026 г. · 4 мин чтения · My Geocode · #postal-code #forms #shipping #autofill

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

Поиск по индексу

Когда покупатель закончил вводить почтовый индекс и выбрал страну, или если страна уже известна из его аккаунта, отправьте оба значения в /v1/postcode.

GET /v1/postcode?code=SW1A 1AA&country=GB

{
  "status": "ok",
  "postcode": "SW1A 1AA",
  "country_code": "GB",
  "results": [
    {"lat": 51.5014, "lon": -0.1419, "components": {"city": "London", "region": "Greater London", "country": "GB"}}
  ]
}

Заполнение полей формы

Заполните поля города и региона напрямую из объекта components в результате и дайте покупателю подтвердить или исправить их, а не блокируйте поля полностью, поскольку почтовый индекс иногда пересекает границу или охватывает несколько распространённых названий мест.

Второй пример: предзаполнение региона плательщика для расчёта налогов

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

Запуск запроса в нужный момент

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

Распространённая ошибка, которой стоит избегать

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

Обработка нераспознанного индекса

Пустой массив results означает, что индекс не распознан для этой страны, чаще всего из-за опечатки. Оставьте поля города и региона пустыми и дайте покупателю заполнить их вручную, а не блокируйте отправку формы, поскольку отклонить поле из-за сбоя автозаполнения хуже для пользователя, чем просто попросить ввести данные вручную в этом единственном случае.

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

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

Точные координаты после ввода полного адреса

Автозаполнение по почтовому индексу даёт местоположение на уровне района, чего достаточно для полей города и региона. Но когда покупатель ввёл ещё и полный адрес улицы, отправка полного адреса в /v1/forward даёт точные координаты, которые на самом деле нужны для транспортной этикетки или системы маршрутизации доставки.

Сколько это стоит

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

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