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

Кожне десяте замовлення в інтернет-магазині втрачається через неправильно введену адресу. Згідно з дослідженням 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 тижні після запуску
• навчання розробників по роботі з рішенням

Типові помилки при самостійній інтеграції