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

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

Представьте: контрагент отправляет заказ, а форма адреса выдаёт ошибку — база устарела, нужного района нет. Клиент теряет время, вы — деньги. Это частая ситуация при работе с 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-совместимости без потери производительности.