Інтеграція КЛАДР для адресних підказок на сайті

Інтеграція КЛАДР для адресних підказок на сайті

Уявіть: контрагент відправляє замовлення, а форма адреси видає помилку — база застаріла, потрібного району немає. Клієнт втрачає час, ви — гроші. Це часта ситуація при роботі з legacy-системами банків та держорганів. Ми вирішуємо її інтеграцією КЛАДР — класифікатора, який досі потрібен для сумісності зі старими API. Наш досвід: 5 років, понад 30 проєктів з адресними підказками, повний цикл — від завантаження бази до фронтенд-інтерфейсу.

КЛАДР формально вважається застарілим (ФНС рекомендує ФІАС/ГАР), але на практиці він живий у банківському секторі, транспортній логістиці та державних системах. DaData, до речі, підтримує обидва стандарти та віддає kladr_id у відповіді. Правильна стратегія — не парсити КЛАДР вручну, а використовувати сучасний інтерфейс з мапінгом.

Структура КЛАДР

База КЛАДР поширюється у DBF-форматі з кодуванням CP866. Основні файли:

Коди КЛАДР мають строгу структуру: 13 цифр для населених пунктів, 17 — для вулиць. За кодом можна однозначно відновити ієрархію адреси.

Завантаження в базу даних

Конвертація DBF в PostgreSQL через Python:

import dbfread import psycopg2 conn = psycopg2.connect("dbname=mydb user=myuser") cur = conn.cursor() table = dbfread.DBF('KLADR.DBF', encoding='cp866') for record in table: cur.execute( "INSERT INTO kladr_objects (code, name, socr, index, gninmb, uno, ocatd, status) " "VALUES (%s, %s, %s, %s, %s, %s, %s, %s)", ( record['CODE'], record['NAME'], record['SOCR'], record['INDEX'], record['GNINMB'], record['UNO'], record['OCATD'], record['STATUS'] ) ) conn.commit() 

Кодування DBF-файлів — CP866, без явного зазначення отримаєте кракозябри. Повна база близько 1–2 ГБ, завантаження займає 20–40 хвилин.

Пошук за КЛАДР

Після завантаження структура таблиць дозволяє шукати за полем NAME з обрізанням активних записів (код не повинен закінчуватися на нулі після певної позиції — це ознака застарілого запису):

SELECT k.name, k.socr, k.code, k.index AS postcode FROM kladr_objects k WHERE k.name ILIKE :query || '%' AND k.code NOT LIKE '%00000' ORDER BY k.name LIMIT 10; 

Для вулиць запит аналогічний, але з таблиці kladr_streets з JOIN на kladr_objects за першими 13 цифрами коду.

Коли КЛАДР, а не ФІАС

Є кілька сценаріїв, де код КЛАДР необхідний принципово:

• Інтеграція з банківськими API (багато банків досі приймають лише КЛАДР-коди для перевірки юрадреси)
• Системи ФНС старого зразка
• Деякі транспортні компанії та логістичні оператори

У таких випадках правильна стратегія — отримати адресу через сучасний інтерфейс (DaData з ФІАС), а у відповіді взяти поле kladr_id, яке DaData повертає для кожного адресного об'єкта.

{ "value": "г Москва, ул Тверская, д 1", "data": { "kladr_id": "7700000000000360004", "fias_id": "5ee84ac0-eb57-4bff-b753-3e0f1ca1b95e", "postal_code": "125009" } } 

Таким чином, користувач вводить адресу в сучасному інтерфейсі, а в БД зберігаються обидва ідентифікатори.

Які проблеми вирішує КЛАДР?

Головний біль — сумісність із застарілими системами. Наприклад, бухгалтерії часто потрібно відправити код КЛАДР у платіж. Якщо ви зберігаєте лише ФІАС, доведеться робити додатковий запит до сервісу. Друга проблема — корекція адрес: багато legacy-сервісів не приймають ФІАС-код і очікують саме КЛАДР. Ми гарантуємо, що після інтеграції всі поля будуть заповнені коректно.

Чому краще використовувати DaData, а не парсити КЛАДР самостійно?

DaData обробляє запит за 50 мс, проти 500 мс для повнотекстового пошуку по КЛАДР в PostgreSQL. Крім того, DaData автоматично оновлюється, а самостійне завантаження КЛАДР вимагає щоквартального оновлення з архівів ФНС. Порівняння підходів:

Якщо вам потрібна виключно сумісність з legacy-сервісами, розумно зберігати обидва ідентифікатори.

Як ми інтегруємо КЛАДР на ваш сайт

1. Аналіз — визначаємо, які поля форми вимагають КЛАДР, які зовнішні системи будуть споживати код.
2. Завантаження бази — конвертуємо свіжий архів КЛАДР у PostgreSQL, налаштовуємо індекси для швидкого пошуку.
3. Розробка API — пишемо ендпоінт для автодоповнення та зворотного геокодування.
4. Інтеграція з фронтендом — підключаємо input з підказками (можна використовувати DaData, але зі збереженням КЛАДР-коду).
5. Тестування — перевіряємо на реальних адресах з банківських та транспортних запитів.

Що входить в інтеграцію

• Розробка модуля завантаження та оновлення бази КЛАДР
• API для пошуку та отримання коду КЛАДР
• Інтерфейс автодоповнення (React/Vue/Angular)
• Документація (схема даних, приклади запитів)
• Підтримка після запуску

Типові помилки при самостійному завантаженні КЛАДР

Строки

Якщо задача — підключити КЛАДР-підказки через власну базу, повний цикл (завантаження, індексування, API, фронтенд) займає 1 робочий день. Якщо КЛАДР-коди потрібні лише для сумісності із зовнішніми системами, а інтерфейс будується на DaData — достатньо половини дня на налаштування мапінгу полів.

Замовте інтеграцію КЛАДР — зв'яжіться з нами, і ми оцінимо ваш проєкт за один день. Гарантуємо збереження legacy-сумісності без втрати продуктивності.