EN · RU

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

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

Содержание

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

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

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

Экран

Раздел ОКТМО — пятый в ленте разделов под заголовком окна. В нём две вкладки:

• КЛЮЧИ И ОБЛАСТЬ — открывается сразу. Это панель: блок Территория (выбор региона и муниципалитета, поиск населённых пунктов), блок Ключи (текущие ключи поиска и кнопки работы с файлом) и блок Пины ОКТМО. Кнопки панели действуют сразу; кнопка ЗАПУСТИТЬ рядом с названием выводит в журнал сводку: готов ли реестр, сколько ключей и пинов.
• ОБНОВИТЬ РОССТАТ — скачать свежий реестр Росстата (обычная операция с полем URL и кнопкой ЗАПУСТИТЬ).

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

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

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

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

Реестр Росстата не найден: data/rosstat. Скачайте снимок во вкладке «ОБНОВИТЬ РОССТАТ».

Откройте вкладку ОБНОВИТЬ РОССТАТ и нажмите ЗАПУСТИТЬ — реестр скачается.

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

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

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

1. Определяется ссылка. По умолчанию открывается страница набора Росстата https://rosstat.gov.ru/opendata/7708234640-oktmo/, из неё выбираются все ссылки вида data-ГГГГММДДTЧЧММ-structure-ГГГГММДДTЧЧММ.csv и берётся файл с наибольшей меткой времени. Если в поле URL указана прямая ссылка на data-*.csv, страница не разбирается — файл берётся напрямую.
2. Файл скачивается во временный data/rosstat/.<имя>.<метка>.tmp мегабайтными блоками. Каждые 10 МБ в журнал пишется отметка прогресса, операцию можно отменить в процессе.
3. Проверяется содержимое. Файл не должен быть пустым, не должен начинаться с <html, и для маленьких файлов проверяется наличие разделителя ;. Если вместо CSV пришла страница ошибки, обновление прерывается, а старый реестр остаётся нетронутым.
4. Файл встаёт на место. Только после проверки временный файл переносится в data/rosstat/.
5. Старые срезы удаляются. Все прежние data-*.csv в папке стираются — остаётся ровно один актуальный файл. Список удалённого попадает в отчёт.
6. Сбрасываются кэши. Разобранные индексы в памяти и файл дискового кэша удаляются.

7. Кэш перестраивается сразу же. Не при следующем открытии экрана, не при первом сопоставлении — немедленно, в той же операции. В журнале появляется строка вида:

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

8. Пишется отчёт report/rosstat_oktmo_update_summary.json: запрошенный и разрешённый URL, путь к файлу, объём загрузки, удалённые срезы, список доступных файлов и итоговый актуальный файл.

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

Где что лежит

Дисковый кэш привязан к пути и времени изменения 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. Введите название в поле поиска и нажмите Найти кандидатов. Поиск идёт внутри выбранного региона, если он задан.
2. Выберите нужную строку в списке под полем поиска. Найденные варианты с кодами показываются в поле предпросмотра.
3. Нажмите Добавить найденные НП — выбранная строка со всеми формами названия уйдёт в текущие ключи.

Пины

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

Файлы:

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

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

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

Флажок Включить ключи ОКТМО (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 — он соберётся заново.