(Оновлено 02.07.2025)

Кодифікатор адміністративно-територіальних одиниць та територій територіальних громад України (КАТОТТГ) у форматі JSON

• 💡 У зв’язку з перейменуванням, утворенням, зміною меж окремих адміністративно-територіальних одиниць дані в кодифікаторі періодично оновлюються. Актуальні дані КАТОТТГ України (Станом на 02.07.2025) знаходяться в кореневому каталозі, попередні версії — в директорії archive. Кодифікатор на поточний момент містить ≈31 740 записів.

📊 Базова версія структури JSON та кілька її модифікацій:

1️⃣. katottg.json (Базова версія) ~ 7.57 Mb

• Опис: Кожна адміністративна одиниця є окремим об'єктом у «плоскому» масиві admin_units. Ієрархія та приналежність до вищих рівнів показана через окремі поля (від level_1 до level_5), що містять коди відповідних адміністративних рівнів. id адміністративної одиниці відповідає коду її самого нижчого рівня.

• Приклад: Для села "Андріївка" (рівень 4) будуть вказані коди області (level_1), району (level_2), громади (level_3) та самого села (id):

  {
    "id": "UA01020010010075540", //код КАТОТТГ
    "name": "Андріївка",
    "category": "C", //Село
    "level": 4, //це адміністративно-територіальна одиниця четвертого рівня
    "level_1": "UA01000000000013043", //Автономна Республіка Крим
    "level_2": "UA01020000000022387", //Бахчисарайський район
    "level_3": "UA01020010000048857" //Андріївська територіальна громада
  }

• Приклад: Для "Андріївської громади" (рівень 3) будуть вказані коди області (level_1), району (level_2), та громади (id):

  {
    "id": "UA01020010000048857",
    "name": "Андріївська",
    "category": "H", //громада
    "level": 3,
    "level_1": "UA01000000000013043",//Автономна Республіка Крим
    "level_2": "UA01020000000022387" //Бахчисарайський район
  }

• Приклад: Для "Автономної Республіки Крим" (рівень 1) буде вказаний тільки код області (id):

  {
    "id": "UA01000000000013043",
    "name": "Автономна Республіка Крим",
    "category": "O",
    "level": 1
  }

• JSON Schema: katottg_schema.json

2️⃣. katottg_minimal.json (Компактна версія) ~ 4.33 Mb

• Опис: Це компактна версія katottg.json: відсутнє форматування (пробіли, відступи), використовуються скорочені назви ключів (i, n, c, l, 1-5) для мінімізації розміру файлу. Включає лише дані адміністративних одиниць та дату останнього оновлення даних у форматі РРРР-ММ-ДД (valid_on).

• Приклад:

  { "i":"UA01020010010075540","n":"Андріївка","c":"C","l":4,"1":"UA01000000000013043","2":"UA01020000000022387","3":"UA01020010000048857" }

• JSON Schema: katottg_minimal_schema.json

3️⃣. katottg_normalized.json (Частково нормалізована версія) ~ 5.23 Mb

• Опис: Кожна адміністративна одиниця є окремим об'єктом у «плоскому» масиві admin_units. Замість кодів всіх вищих адміністративних рівнів(від level_1 до level_5) кожен запис містить лише parent_id – ідентифікатор безпосереднього батьківського елемента в ієрархії. У адміністративних одиниць першого рівня parent_id відсутній.

• Приклад: Для села "Андріївка" (id: UA01020010010075540) його parent_id буде кодом "Андріївської територіальної громади" (UA01020010000048857):

  {
    "id": "UA01020010010075540",
    "parent_id": "UA01020010000048857",
    "name": "Андріївка",
    "category": "C",
    "level": 4
  }

• JSON Schema: katottg_normalized_schema.json

4️⃣. katottg_normalized_minimal.json (Компактна частково нормалізована версія) ~ 2.80 Mb

• Опис: Це компактна версія katottg_normalized.json: відсутнє форматування (пробіли, відступи), використовуються скорочені назви ключів (i, n, c, l, 1-5) для мінімізації розміру файлу. Включає лише дані адміністративних одиниць та дату останнього оновлення даних у форматі РРРР-ММ-ДД (valid_on).

• Приклад:

  { "i":"UA01020010010075540","p":"UA01020010000048857","n":"Андріївка","c":"C","l":4 }

• JSON Schema: katottg_normalized_minimal_schema.json

5️⃣. katottg_tree.json (ієрархічна структура) ~ 7.79 Mb

• Опис: Дані КАТОТТГ у вигляді вкладеної деревоподібної структури. Кожна адміністративна одиниця містить масив items зі своїми безпосередніми дочірніми елементами та parent_id – ідентифікатором безпосереднього батьківського елемента в ієрархії.
• Приклад об’єктів в admin_units:

  {
    "id": "UA01000000000013043",
    "name": "Автономна Республіка Крим",
    "category": "O",
    "level": 1,
    "items": [
      {
        "id": "UA01020000000022387",
        "parent_id": "UA01000000000013043",
        "name": "Бахчисарайський",
        "category": "P",
        "level": 2,
        "items": [
          {
           "id": "UA01020010000048857",
            "parent_id": "UA01020000000022387",
            "name": "Андріївська",
            "category": "H",
            "level": 3
          }
        ]
      }
    ]
  }

• JSON Schema: katottg_tree_schema.json

📋 Список скорочень, що використовуються в КАТОТТГ для позначення об’єктів,

1. «Перший рівень» – Автономна Республіка Крим, область, місто, що має спеціальний статус;
2. «Другий рівень» – район в Автономній Республіці Крим, області;
3. «Третій рівень» – територіальна громада;
4. «Четвертий рівень» – місто, селище, село (населений пункт);
5. «Додатковий рівень» – район у місті (у тому числі в місті, що має спеціальний статус);
6. «Категорія об’єкта», де:
   • «O» – Автономна Республіка Крим, область;
   • «K» – місто, що має спеціальний статус;
   • «P» – район в Автономній Республіці Крим, області;
   • «H» – територіальна громада;
   • «M» – місто;
   • «X» – селище;
   • «C» – село;
   • «B» – район у місті.

• ❗ «O»,«K»,«P»,«H»,«M»,«X»,«C»,«B» — це літери латинського алфавіту

🔑 Повні та скорочені ключі

У мінімальних версіях файлів КАТОТТГ (katottg_minimal.json, katottg_normalized_minimal.json) використовуються скорочені назви ключів для зменшення розміру файлу.

Повний ключ	Скорочений ключ	Опис
id	i	Код згідно КАТОТТГ
parent_id	p	Ідентифікатор батьківського елемента
name	n	Назва адміністративної одиниці
category	c	Категорія адміністративної одиниці
level	l	Рівень адміністративної одиниці в ієрархії КАТОТТГ
level_1	1	Код Першого рівня
level_2	2	Код Другого рівня
level_3	3	Код Третього рівня
level_4	4	Код Четвертого рівня
level_5	5	Код Додаткового рівня
items	s	Список дочірніх адміністративних одиниць (використовується тільки в ієрархічній структурі)

⚖ Вихідну інформацію для створення JSON файлів взято з офіційних відкритих джерел. Важливо розуміти, що ця сторінка не є офіційним джерелом даних і створена для зручності спільноти.