ОКТМО и ключи проекта

English · Руководство · Справочник

Содержание

• Экран
• Реестр: скачивание и обновление
• Область поиска: регион и муниципалитет
• Ключи поиска
• Пины
• Как ОКТМО используется в работе
• Если что-то пошло не так

ОКТМО — Общероссийский классификатор территорий муниципальных образований. Программа использует его как источник правды о том, какие населённые пункты существуют внутри выбранного региона и муниципалитета, и как они официально называются.

Без реестра адресный разбор продолжает работать, но теряет территориальный контекст: списки регионов и муниципалитетов пусты, а похожие названия из разных районов ничем не разделяются. С реестром — сопоставление сужается до нужной территории, а слоты OKTMO_Code и OKTMO_Name заполняются кодом и официальным наименованием.

Экран

Плитка ОКТМО / ключи проекта — первая в списке команд. Она открывает экран Ключи и область ОКТМО сразу, без промежуточного меню.

Сверху экрана две кнопки:

• ОБНОВИТЬ БАЗУ ДАННЫХ ОКТМО — скачать свежий реестр Росстата.
• СБРОСИТЬ КЛЮЧИ ОКТМО — очистить текущие ключи поиска. Пины при этом

сохраняются.

Ниже — блок Территория: выбор региона, выбор муниципалитета, панель ключей, поиск населённых пунктов и панель пинов.

Реестр: скачивание и обновление

Реестр скачивается кнопкой. Ничего копировать руками и класть в папку не нужно.

Пока файла реестра нет, под полем региона висит красная полоса:

Реестр ОКТМО не найден: data/rosstat/data-\*.csv. Списки регионов и

муниципалитетов будут неполными.

Справа в этой же полосе — кнопка СКАЧАТЬ ОКТМО. Она запускает ту же операцию, что и ОБНОВИТЬ БАЗУ ДАННЫХ ОКТМО сверху экрана. Разница только в том, что первая появляется, когда реестра нет, а вторая доступна всегда.

Обновление — это та же кнопка. Отдельной операции «обновить» не существует: и первая загрузка, и последующие обновления делаются одним и тем же действием. Когда Росстат публикует новый месячный срез, достаточно ещё раз нажать ОБНОВИТЬ БАЗУ ДАННЫХ ОКТМО.

Как только полоса сменится строкой Реестр ОКТМО: data-…-structure-….csv, реестр на месте.

Что происходит при нажатии

1. Определяется ссылка. По умолчанию открывается страница набора Росстата

https://rosstat.gov.ru/opendata/7708234640-oktmo/, из неё выбираются все ссылки вида data-ГГГГММДДTЧЧММ-structure-ГГГГММДДTЧЧММ.csv и берётся файл с наибольшей меткой времени. Если в поле URL указана прямая ссылка на data-*.csv, страница не разбирается — файл берётся напрямую.

1. Файл скачивается во временный data/rosstat/.<имя>.<метка>.tmp

мегабайтными блоками. Каждые 10 МБ в журнал пишется отметка прогресса, операцию можно отменить в процессе.

1. Проверяется содержимое. Файл не должен быть пустым, не должен начинаться

с <html, и для маленьких файлов проверяется наличие разделителя ;. Если вместо CSV пришла страница ошибки, обновление прерывается, а старый реестр остаётся нетронутым.

1. Файл встаёт на место. Только после проверки временный файл переносится в

data/rosstat/.

1. Старые срезы удаляются. Все прежние data-*.csv в папке стираются —

остаётся ровно один актуальный файл. Список удалённого попадает в отчёт.

1. Сбрасываются кэши. Разобранные индексы в памяти и файл дискового кэша

удаляются.

1. Кэш перестраивается сразу же. Не при следующем открытии экрана, не при

первом сопоставлении — немедленно, в той же операции. В журнале появляется строка вида:

copy   OKTMO cache ready: regions=…, index_keys=…, contexts=…, bytes=…

1. Пишется отчёт report/rosstat_oktmo_update_summary.json: запрошенный и

разрешённый URL, путь к файлу, объём загрузки, удалённые срезы, список доступных файлов и итоговый актуальный файл.

После завершения списки регионов и муниципалитетов в окне сразу отражают новый реестр — кэши опций интерфейса сбрасываются вместе с индексами.

Где что лежит

Путь	Что это
data/rosstat/data-*.csv	Сам реестр. Всегда ровно один файл
data/rosstat/oktmo_lookup_cache.json	Разобранный индекс для быстрого поиска
report/rosstat_oktmo_update_summary.json	Отчёт последнего обновления

Дисковый кэш привязан к пути и времени изменения CSV и к версии формата кэша. Подменённый вручную файл реестра обесценивает кэш автоматически — индекс будет собран заново при первом обращении. Отдельно чистить кэш не нужно.

Ручные настройки

Поле URL. В параметрах операции обновления можно указать другой адрес: страницу набора или прямую ссылку на data-*.csv. Пустое значение и значение по умолчанию равнозначны.

Переменные окружения. Если поле пустое, адрес берётся из первой заданной переменной: AUDION_ADDRESS_PROCESSOR_ROSSTAT_OKTMO_URL, AUDION_ROSSTAT_OKTMO_URL, AAP_ROSSTAT_OKTMO_URL.

Папка данных ОКТМО. Дополнительное поле «Папка данных ОКТМО» переносит реестр в другое место. Указывается папка, содержащая rosstat/; если указать саму rosstat, будет взята родительская. Пустое значение — папка data проекта.

Область поиска: регион и муниципалитет

Регион ОКТМО — выпадающий список, построенный по локальному срезу реестра. Поле с поиском: набранный текст фильтрует список.

Муниципалитет ОКТМО — список строится внутри выбранного региона. При смене региона выбранный муниципалитет сбрасывается, а его список перестраивается.

Справа от каждого из этих полей — три кнопки:

Кнопка	Действие
Закрепить (кнопка с булавкой)	Поднять значение в начало списка. Повторное нажатие поднимает уже закреплённое значение выше
Открепить (кнопка с минусом)	Снять закрепление
Добавить (кнопка с плюсом)	Добавить выбранный регион или МО в файл ключей поиска

Плюс на поле муниципалитета добавляет не только само МО, но и все его населённые пункты со всеми падежными формами названий. Это основной способ набрать ключи для района целиком.

Ключи поиска

Ключи — это список названий, по которым программа опознаёт «свою» территорию в сыром тексте адреса. Названия хранятся в падежных формах, потому что в реальных таблицах встречается и «Синегорск», и «Синегорска», и «Синегорске».

Файл: config/oktmo_current_keys.txt, по одной строке на форму.

Панель Текущие ключи показывает счётчик, путь к файлу и сами ключи. Иконка копирования кладёт весь список в буфер, иконка разворота открывает его во весь экран.

Кнопки панели:

Кнопка	Действие
Открыть	Открыть файл ключей во внешнем редакторе
Сохранить	Записать в файл ключи выбранного региона и МО
Загрузить	Перечитать файл с диска
Очистить	Опустошить файл ключей

СБРОСИТЬ КЛЮЧИ ОКТМО сверху экрана делает то же, что «Очистить», и вдобавок сбрасывает выбранные регион, муниципалитет и поля поиска населённого пункта. Пины остаются.

Поиск отдельных населённых пунктов

Когда нужен не весь район, а несколько посёлков:

1. Введите название в поле поиска и нажмите Найти кандидатов. Поиск идёт

внутри выбранного региона, если он задан.

1. Выберите нужную строку в списке Точная строка ОКТМО. Найденные варианты

с кодами показываются в поле предпросмотра.

1. Нажмите Добавить найденные НП — выбранная строка со всеми формами

названия уйдёт в текущие ключи.

Пины

Пин — это закреплённое значение региона или МО, которое всегда показывается в начале выпадающего списка. Пины не влияют на сопоставление, они экономят время при работе с одними и теми же территориями.

Файлы:

Путь	Что это
config/oktmo_region_pins.json	Закреплённые регионы
config/oktmo_municipality_pins.json	Закреплённые муниципалитеты
config/oktmo_pins_bundle.json	Общий набор, обновляется автоматически

Панель Пины ОКТМО:

Кнопка	Действие
Открыть пины	Открыть файл пинов во внешнем редакторе
Экспорт пинов	Сохранить копию с меткой времени
Импорт пинов	Загрузить набор пинов из файла
Очистить пины ОКТМО	Удалить все пины

Импорт и очистка сбрасывают кэши списков, поэтому изменения видны сразу.

Как ОКТМО используется в работе

Флажок Включить ключи ОКТМО (use_oktmo) есть на экранах сбора адресов, сопоставления адресов, нормализации эталона и обработки эталона.

Когда флажок включён:

• при разборе адреса ищется совпадение с ключами проекта и определяется

территориальный контекст: субъект, муниципалитет, населённый пункт;

• найденный контекст пишется в слоты OKTMO_Code и OKTMO_Name;
• при сопоставлении пара с несовместимым территориальным кодом отбрасывается

ещё до подсчёта похожести, а совпадение по территории добавляет вес нужному кандидату.

Именно поэтому «улица Ленина, 12» из двух соседних районов не склеивается в одну строку.

Если реестра нет, флажок остаётся рабочим, но контекст взять неоткуда: слоты ОКТМО останутся пустыми, а территориальная проверка выродится в сравнение текстовых названий.

Если что-то пошло не так

**«Could not find a Rosstat OKTMO data-\*.csv link».** На странице не нашлось ни одной подходящей ссылки — Росстат изменил вёрстку или страница недоступна. Откройте набор в браузере, скопируйте прямую ссылку на data-*.csv и вставьте её в поле URL.

«Downloaded Rosstat OKTMO payload looks like HTML, not CSV». Вместо файла пришла страница — как правило, заглушка или ошибка сети. Старый реестр не пострадал, повторите попытку.

Списки регионов пусты, хотя файл на месте. Проверьте, что файл лежит именно в data/rosstat/ и его имя соответствует шаблону data-*.csv. Если папка переопределена полем «Папка данных ОКТМО», реестр ищется там.

Реестр обновился, а списки старые. Такого быть не должно: кэш перестраивается в той же операции. Если это всё же случилось, удалите data/rosstat/oktmo_lookup_cache.json — он соберётся заново.