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

Каждый десятый заказ в интернет-магазине теряется из-за неправильно введённого адреса. Согласно исследованию 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 обойдётся примерно в $27–39/мес, а собственный сервер — около $9–13/мес с учётом хостинга.

Производительность 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 недели после запуска
• обучение разработчиков по работе с решением

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