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

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

КЛАДР (Классификатор адресов России) — более старый стандарт адресной базы по сравнению с ФИАС/ГАР. Формально он считается устаревшим: ФНС прекратила его обновление, рекомендуя переходить на ФИАС. Тем не менее на практике КЛАДР до сих пор встречается в проектах — особенно в связке с банковскими и государственными системами, которые ещё не мигрировали. DaData поддерживает оба стандарта и отдаёт коды КЛАДР в ответе наряду с ФИАС-идентификаторами.

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

База КЛАДР распространяется в формате DBF. Основные файлы:

Коды КЛАДР имеют строгую структуру: 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"
  }
}

Таким образом, пользователь вводит адрес в современном интерфейсе, а в БД сохраняются оба идентификатора.

Сроки

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