Класифікатор КАТОТТГ. Оновити структуру і наповнення

Ще в 2021 році класифікатор КОАТУУ перестав підтримуватись на державному рівні, але ми досі його використовуємо.

Цитата: "У зв’язку з прийняттям Постанови Верховної Ради України від 17.07.2020 № 807-IX "Про утворення та ліквідацію районів" КОАТУУ втратив актуальність. Міністерством розвитку громад та територій розроблено та затверджено Кодифікатор адміністративно-територіальних одиниць та територій територіальних громад (наказ від 26.11.2020 № 290 зі змінами, внесеними наказом від 12.01.2021 № 3), який відповідає чинному законодавству і запроваджується на заміну КОАТУУ"

Для сервісу процедур окремою таскою буде реалізовано перехід з КОАТУУ на КАТОТТГ. В цій тасці мова про актуалізацію існуючого класифікатора КАТОТТГ

Бізнес-опис: Був проведений аналіз і пошук джерела, звідки можна отримувати актуальні класифікатора, бо він постійно змінюється.

ДІЯ утримує не актуальний з 2021 року довідник тут
ДержСтат тримає не актуальний класифікатор тут
Міністерство розвидку громад та територій України має актуальний класифікатор тут

але у вигляді файлів. API відсутнє.

Пошук НЕ офіційних джерел дає результат у вигляді API, але класифікатори там також НЕ актуальні. Їх ніхто не підтримує..

Єдиний знайдений варіант, де можна забрати актуальну інформацію по КАТОТТГ - Міністерство розвидку громад та територій України.

Задача: Забрати актуальні дані по класифікатору і оновити існуючий на ЦБД. Мати можливість оновлювати класифікатор з періодичністю "раз на рік" по запиту.

Технічний підхід:

Необхідно реалізувати функціонал, який дозволить обробити файл:

Кодифікатор_22_10_2024.xlsx

і сформувати класифікатор, який має повертатися в JSON по API.

Warning! На момент реалізації бажано забрати актуальний на той момент файл з сайту

Не передбачається автоматичного оновлення, бо інколи Міністерство чомусь викладає файл в іншому форматі чи структурі. Тому, тільки ручне оновлення раз на рік чи в іншому інтервалі.

Вигляд обʼєкта в JSON, який потрібно зробити (це приклад. Реалізація може відрізнятися):

{
    "UA32080050020065009": {
        "code": "UA32080050020065009",
        "name": {
            "uk_UA": "Софіївська Борщагівка",
            "en_US": ""
        },
        "level": 4,
        "parent_id": "UA32080050000052660",
        "category": "C",
        "deprecated": false
    },
    "UA32080050000052660": {
        "code": "UA32080050000052660",
        "name": {
            "uk_UA": "Борщагівська",
            "en_US": ""
        },
        "level": 3,
        "parent_id": "UA32080000000084076",
        "category": "H",
        "deprecated": false
    },
    "UA32080000000084076": {
        "code": "UA32080000000084076",
        "name": {
            "uk_UA": "Бучанський",
            "en_US": ""
        },
        "level": 2,
        "parent_id": "UA32000000000030281",
        "category": "P",
        "deprecated": false
    },
    "UA32000000000030281": {
        "code": "UA32000000000030281",
        "name": {
            "uk_UA": "Київська",
            "en_US": ""
        },
        "level": 1,
        "parent_id": null,
        "category": "O",
        "deprecated": false
    },
    "UA80000000000093317": {
        "code": "UA80000000000093317",
        "name": {
            "uk_UA": "Київ",
            "en_US": ""
        },
        "level": 1,
        "parent_id": null,
        "category": "K",
        "deprecated": false
    },
    "UA80000000000624772": {
        "code": "UA80000000000624772",
        "name": {
            "uk_UA": "Печерський",
            "en_US": ""
        },
        "level": 5,
        "parent_id": "UA80000000000093317",
        "category": "B",
        "deprecated": false
    }
}

де логіка мапінгу наступна:

"UA32080050020065009"

- ключ обʼєкта у класифікаторі. Для його визначення потрібно взяти останній код із рядка Excel.

"code": "UA32080050020065009",

код класифікатора. Дублюється із ключа

"name": {
            "uk_UA": "Софіївська Борщагівка",
            "en_US": ""
        },

назва обʼєкта. "uk_UA" наповнюється значенням із G колонки Excel. en_US - не наповнюється.

"level": 4,

рівень класифікатора. Наповнюється значенням в залежності від колонки, в якій розміщено останній код в рядку. В прикладі вище, останній код в колонці D (заголовок колонки "Четвертий рівень") тому і level == 4

"parent_id": "UA32080050000052660",

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

Для прикладу вище, це значення із C колонки "Третій рівень" == UA32080050000052660

Для коду "Першого рівня" parent_id is null

"category": "C"

Категорія із переліку:

«O» – Автономна Республіка Крим, область;
«K» – місто, що має спеціальний статус;
«P» – район в Автономній Республіці Крим, області;
«H» – територіальна громада;
«M» – місто;
«X» – селище;
«C» – село;
«B» – район у місті.

P.S.: "власник" цих даних використовує то кирилічні символи, то латиницю... якщо автоматизовувати, то треба це враховувати..

Для наповнення потрібно із колонки F забрати значення.

"deprecated": false

boolean type поле.

Якщо в оновленому файлі-джерелі код стає відсутнім (населений пункт прибрали), але такий код є в Довіднику, то необхідно для нього проставити

"deprecated": true

Особливості

Код унікальний в рамках рівня, але не унікальний в рамках всієї таблиці.

Парситься так:

    "UA80000000000624772": {
        "code": "UA80000000000624772",
        "name": {
            "uk_UA": "Печерський",
            "en_US": ""
        },
        "level": 5,
        "parent_id": "UA80000000000093317",
        "category": "B",
        "deprecated": false
    }

можливі дії, які необхідно враховувати:

В файлі може зʼявитись новий населений пункт. Його код буде унікальний в рамках рівня.
В файлі може зникнути населений пункт. Це означає, що він припинив своє існування, або його обʼєднали з найближчим.
1. Важливо: код, який використовувався для населеного пункту, повторно НЕ використовується для іншого НП.
Населений пункт може змінити назву чи категорію, але не може змінити код. Якщо змінюється код, то це вже інший населений пункт.

Edited Apr 14, 2025 by Philip