EN · RU

OKTMO and Project Keys

Русский · User Guide · Reference

Contents

• The Screen
• The Registry: Download and Update
• Search Scope: Region and Municipality
• Search Keys
• Pins
• How OKTMO Is Used in Work
• When Something Goes Wrong

OKTMO is the Russian Classifier of Municipal Territories. The program uses it as the source of truth for which settlements exist inside a chosen region and municipality, and what their official names are.

Without the registry, address parsing still works but loses territorial context: region and municipality lists are empty, and similar names from different districts are nothing apart. With the registry, matching narrows down to the intended territory and the OKTMO_Code and OKTMO_Name slots are filled with the code and the official name.

The Screen

The OKTMO section is the fifth in the row of sections under the window header. It has two tabs:

• KEYS & AREA — opens at once. It is a panel: the Territory block (choice of region and municipality, settlement search), the Keys block (the current search keys and the buttons for the file) and the OKTMO pins block. The buttons of the panel act at once; the RUN button beside the title writes a summary into the journal: whether the registry is ready, how many keys and pins there are.
• UPDATE ROSSTAT — download a fresh Rosstat registry (an ordinary operation with a URL field and a RUN button).

The line above the region field shows which registry file is in use now.

The Registry: Download and Update

The registry is downloaded by a button. Nothing has to be copied by hand and placed into a folder.

While the registry file is missing, the line above the region field says (in amber):

The Rosstat registry was not found: data/rosstat. Download the snapshot in the UPDATE ROSSTAT tab.

Open the UPDATE ROSSTAT tab and press RUN — the registry downloads.

Updating is the same operation. There is no separate "update" operation: the first download and every later refresh are the same action. When Rosstat publishes a new monthly snapshot, run UPDATE ROSSTAT again.

Once the line above the region field changes to Rosstat registry: data-…-structure-….csv, the registry is in place.

What Happens on Click

1. The link is resolved. By default the Rosstat dataset page https://rosstat.gov.ru/opendata/7708234640-oktmo/ is opened, every link of the form data-YYYYMMDDTHHMM-structure-YYYYMMDDTHHMM.csv is collected, and the file with the highest timestamp is taken. If the URL field holds a direct data-*.csv link, the page is not parsed — the file is taken directly.
2. The file is downloaded to a temporary data/rosstat/.<name>.<stamp>.tmp in one-megabyte chunks. Every 10 MB a progress line is written to the log, and the operation can be cancelled mid-download.
3. The payload is validated. The file must not be empty, must not start with <html, and for small files the semicolon separator is checked. If an error page arrived instead of CSV, the update aborts and the old registry stays untouched.
4. The file is put in place. Only after validation is the temporary file moved into data/rosstat/.
5. Old snapshots are removed. Every previous data-*.csv in the folder is deleted — exactly one current file remains. What was removed goes into the report.
6. Caches are dropped. Parsed in-memory indexes and the disk cache file are discarded.

7. The cache is rebuilt immediately. Not on the next screen open, not on the first match — right away, within the same operation. The log shows a line like:

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

8. A report is written to report/rosstat_oktmo_update_summary.json: the requested and resolved URL, the file path, the downloaded size, removed snapshots, the list of available files, and the resulting current file.

When it finishes, the region and municipality lists in the window reflect the new registry at once — the UI option caches are dropped together with the indexes.

Where Things Live

The disk cache is keyed to the CSV path and modification time and to the cache format version. A registry file replaced by hand invalidates the cache automatically — the index is rebuilt on first use. There is no need to clean the cache separately.

Manual Settings

The URL field. The update operation accepts a different address: the dataset page or a direct data-*.csv link. An empty value and the default value are equivalent.

Environment variables. When the field is empty, the address comes from the first variable that is set: AUDION_ADDRESS_PROCESSOR_ROSSTAT_OKTMO_URL, AUDION_ROSSTAT_OKTMO_URL, AAP_ROSSTAT_OKTMO_URL.

OKTMO data folder. The advanced OKTMO data folder field moves the registry elsewhere. Give the folder that contains rosstat/; naming rosstat itself resolves to its parent. Empty means the project data folder.

Search Scope: Region and Municipality

OKTMO search region is a list built from the local registry snapshot. The open list has a search line: typed text filters it.

OKTMO municipality is built inside the selected region. Changing the region clears the selected municipality and rebuilds its list.

Three buttons sit to the right of each field:

Add on the municipality field contributes not only the municipality itself but all of its settlements with every grammatical form of their names. This is the main way to collect keys for a whole district.

Search Keys

Keys are the list of names by which the program recognises "its own" territory in raw address text. Names are stored in grammatical forms, because real tables contain «Синегорск», «Синегорска», and «Синегорске» alike.

File: config/oktmo_current_keys.txt, one form per line.

The Current keys panel shows the counter, the file path, and the keys themselves. The copy icon puts the whole list on the clipboard; the expand icon opens it full screen.

Panel buttons:

RESET OKTMO KEYS in the same block does what Clear does, and in addition resets the selected region, municipality, and settlement search fields. Pins remain.

Searching for Individual Settlements

When you need a few villages rather than a whole district:

1. Type the name into the search field and press Find candidates. The search runs inside the selected region when one is set.
2. Choose the row you need in the list under the search field. Found variants with codes are shown in the preview field.
3. Press Add found places — the selected row with every form of its name goes into the current keys.

Pins

A pin is a fixed region or municipality value that is always shown at the top of the dropdown. Pins do not affect matching; they save time when you work with the same territories repeatedly.

Files:

The OKTMO pins panel:

Import and clear drop the list caches, so changes are visible immediately.

How OKTMO Is Used in Work

The Enable OKTMO keys checkbox (use_oktmo) appears on the address collection, address alignment, reference normalization, and reference processing screens.

When it is on:

• address parsing looks for a match against the project keys and determines the territorial context: subject, municipality, settlement;
• the found context is written into the OKTMO_Code and OKTMO_Name slots;
• during matching, a pair with an incompatible territory code is discarded before similarity is even scored, while a territory match adds weight to the right candidate.

That is why "улица Ленина, 12" from two neighbouring districts does not collapse into one row.

Without the registry the checkbox still works, but there is no context to take: the OKTMO slots stay empty and the territorial check degenerates into comparing text names.

When Something Goes Wrong

"Could not find a Rosstat OKTMO data-*.csv link". No suitable link was found on the page — Rosstat changed the markup, or the page is unavailable. Open the dataset in a browser, copy the direct data-*.csv link, and paste it into the URL field.

"Downloaded Rosstat OKTMO payload looks like HTML, not CSV". A page arrived instead of a file — usually a stub or a network error. The old registry is unharmed; try again.

Region lists are empty although the file is there. Check that the file sits in data/rosstat/ and its name matches the data-*.csv pattern. If the folder is overridden by the OKTMO data folder field, the registry is looked for there.

The registry updated but the lists are stale. This should not happen: the cache is rebuilt within the same operation. If it does, delete data/rosstat/oktmo_lookup_cache.json — it will be rebuilt.