Интеграция ФИАС для адресных подсказок на сайте

Каждый десятый заказ в интернет-магазине теряется из-за неправильно введённого адреса. Согласно исследованию DataInsight, до 15% посылок не доходят до получателя с первой попытки — чаще всего из-за ошибок в адресе. Пользователь не знает точной улицы, путает район, пропускает корпус. Мы решаем это с помощью автодополнения адресов на основе ФИАС. Наш опыт — 5 лет и 20 успешных проектов. Для 10 интернет-магазинов количество ошибок снизилось с 15% до 1%. Предлагаем два пути: облачный сервис DaData или собственная инфраструктура на PostgreSQL. Собственный сервер окупается при нагрузке от 5 тысяч запросов в день. Разберём технические детали: от загрузки дампов до фронтенда. Используем дельта-обновления, GIN-индексы и кеширование.

Как интегрировать ФИАС без посредников?

Прямая интеграция оправдана в трёх случаях: требования ИБ не позволяют отправлять адреса во внешние API, ожидается высокая нагрузка (десятки тысяч запросов в сутки), нужна кастомная логика поиска. В остальных случаях проще и дешевле использовать DaData.

Получение и загрузка дампов

Актуальные дампы публикуются на официальном сайте ФИАС. Доступны полная база (XML, несколько десятков архивов, общий объём сжатых данных — около 2 ГБ) и дельта-обновления (еженедельные). Формат ГАР немного отличается, но принципы те же.

Минимальный набор таблиц для адресных подсказок:

• AS_ADDR_OBJ — регионы, районы, города, улицы
• AS_HOUSES — дома, строения, корпуса
• AS_HIERARCHY — иерархические связи объектов
• AS_ADDR_OBJ_PARAMS — дополнительные параметры (почтовый индекс)

Первая загрузка полного дампа в PostgreSQL через php-скрипт или python-парсер занимает 3–6 часов. Дельта-обновления — 10–30 минут.

Структура таблиц и индексы

CREATE TABLE addr_obj ( id UUID PRIMARY KEY, object_id BIGINT, name TEXT NOT NULL, type_name TEXT, level SMALLINT, is_active BOOLEAN DEFAULT true ); CREATE TABLE houses ( id UUID PRIMARY KEY, object_id BIGINT, addr_obj_id BIGINT, house_num TEXT, build_num TEXT, struct_num TEXT, is_active BOOLEAN DEFAULT true ); CREATE INDEX idx_addr_obj_name_fts ON addr_obj USING GIN (to_tsvector('russian', name)); CREATE INDEX idx_hierarchy_parent ON hierarchy(parent_obj_id); CREATE INDEX idx_hierarchy_child ON hierarchy(object_id); 

Без GIN-индекса поиск по 30+ млн записей будет нестерпимо медленным. Документация PostgreSQL по GIN-индексам рекомендует именно такой подход для полнотекстового поиска на русском языке.

API для подсказок

Простой endpoint на PHP/Laravel, который принимает строку и возвращает список вариантов:

public function suggest(Request $request): JsonResponse { $query = trim($request->input('q', '')); if (mb_strlen($query) < 2) { return response()->json([]); } $results = DB::select(" SELECT ao.name, ao.type_name, ao.level, h.path_name FROM addr_obj ao JOIN addr_hierarchy h ON h.object_id = ao.object_id WHERE to_tsvector('russian', ao.name) @@ plainto_tsquery('russian', ?) AND ao.is_active = true ORDER BY ao.level, ao.name LIMIT 10 ", [$query]); return response()->json($results); } 

Для ввода домов запрос сложнее — нужно сначала найти улицу по её object_id, затем искать дома по addr_obj_id. В нашей практике среднее время выполнения такого составного запроса не превышает 80 мс после прогрева кеша.

Фронтенд: подключение подсказок

На стороне браузера — стандартная логика debounce + fetch:

let timer; input.addEventListener('input', () => { clearTimeout(timer); timer = setTimeout(async () => { const q = input.value.trim(); if (q.length < 2) return; const res = await fetch(`/api/fias/suggest?q=${encodeURIComponent(q)}`); const data = await res.json(); renderDropdown(data); }, 250); }); 

Задержка 250 мс исключает запрос на каждый нажатый символ. Для улучшения UX мы добавляем индикатор загрузки и обрабатываем ошибки — пользователь не должен видеть пустой дропдаун при сетевом сбое.

Когда собственная инфраструктура оправдана?

Сравним подходы:

Если объём запросов высокий, собственный сервер дешевле в долгосрочной перспективе. Например, при 10 000 запросов в день DaData обойдётся примерно в 3000 руб/мес, а собственный сервер — около 1000 руб/мес с учётом хостинга.

Производительность API

Процесс работы

1. Анализ требований — определяем нагрузку, необходимость закрытого контура, выбираем подход.
2. Подготовка инфраструктуры — настраиваем сервер (Linux, PostgreSQL, Docker) или подключаемся к DaData.
3. Загрузка и индексация дампа — загружаем полный дамп ФИАС/ГАР, создаём GIN-индексы.
4. Разработка REST API — реализуем endpoint для подсказок с учётом иерархии.
5. Интеграция фронтенда — подключаем AJAX-запросы к API, настраиваем debounce и рендер.
6. Автообновление — настраиваем cron для ежедневного скачивания и применения дельт.
7. Тестирование и документация — проверяем корректность подсказок, пишем API-документацию.

Что входит в работу

• документация по интеграции (API-спецификация, описание таблиц)
• доступ к API (если разворачиваем на вашем сервере) или инструкция по подключению к DaData
• скрипты для автообновления данных
• техническая поддержка 2 недели после запуска
• обучение разработчиков по работе с решением

Типичные ошибки при самостоятельной интеграции