ua-geo-set

🇺🇦 UaGeoSet 🇺🇦

UaGeoSet is a zero-dependency TypeScript/JavaScript library that wraps a pre-compiled JSON snapshot of the Ukrainian administrative-territorial catalogue (KATOTTG) as of 2024. It exposes a simple GeoAPI class to query regions, districts, communities, and settlements by their official UA-codes (in KATOTTG style).

Key Characteristics

• Zero Dependencies: Pure TypeScript implementation
• Lightweight: Bundles only a minimal, index-based JSON (kattog.json), optimized from the original KATOTTG dataset
• Offline First: No external network requests—everything works offline
• Type-Safe: Full TypeScript support with proper interfaces [Almost]
• Universal: Works in both Node.js and browser environments

Data Coverage

The library provides access to the complete Ukrainian administrative hierarchy:

• Regions (Області) and AR Crimea
• Districts (Райони)
• Communities (Громади)
• Settlements (Населені пункти)

💡 The optimization process reduces the original dataset size while maintaining all essential information and relationships.

Table of Contents:

• 📊 Data Source
  • Data Processing Pipeline
• Features
• Installation
• Data Model & Categories
  • The KATOTTG to API Categories Table
• 🧑‍💻 Basic Usage
  • Initializing the API
  • Regions
  • Districts
  • Communities
  • Settlements
  • Search Examples
• Folder Structure
• CHANGELOG
• License

📊 Data Source

The library is built on top of the official KATOTTG 2024 dataset, which is maintained by kaminarifox.

Data Processing Pipeline

• Source Data: Raw KATOTTG JSON from (data/raw-kattog.json)
• Optimization: Custom script (scripts/optimize-kattog.ts) transforms the data into a compact, index-based format
• Output: Optimized JSON (data/kattog.json) with minimal footprint and fast lookups

💡 The optimization process reduces the original dataset size (9.7MB -> 2.3MB) while maintaining all essential information and relationships.

Features

• Official UA-codes for every administrative unit (exactly as in KATOTTG).
• Covers the full hierarchy (2024):
  • Regions and AR Crimea / Області та Автономна Республіка Крим
  • Cities with special status / Міста, що мають спеціальний статус (e.g. Kyiv, Sevastopol)
  • Districts in regions and AR Crimea / Райони в областях та Автономній Республіці Крим
  • Territorial communities / Території територіальних громад (names of territorial communities in each oblast, including Crimea)
  • Cities / Міста
  • Urban-type settlements / СМТ (deprecated; now treated under "Cелища")
  • Villages / Села
  • Settlements / Селища
  • City districts / Райони в містах
• Lightweight: index-based JSON, no redundant fields, minimal footprint.
• Fully TypeScript-typed: you get Region, District, Community, and Settlement interfaces, each with its UA-code, name, category, and parent/children relationships.
• No runtime dependencies—suitable for both browser and Node.js.

Installation

Using npm (preferred):

npm add ua-geo-set

Or with npm:

npm install ua-geo-set

Yarn:

yarn add ua-geo-set

Data Model & Categories

The 2024 KATOTTG hierarchy is represented by a single JSON (kattog.json) with two arrays:

• indexToCode: string[]
  • Maps each numeric index to a UA-code (e.g. "UA02000000000045678")
• items: RawItem[]
  • Each RawItem contains:
    • name: string – the official name (e.g., "Вінницька область", "Київ")
    • category: CategoryCode – one of { O, K, P, H, C, X, M, B }
    • parent?: number – numeric index of its parent (if any)
    • children?: number[] – array of numeric indices of its children (if any)
    • independent?: boolean – set to true for "independent" city-regions (K) like Kyiv and Sevastopol

The KATOTTG to API Categories Table:

Code	Alias	Description (Ukrainian)	Description (English)	Notes
O	Region	Області та АР Крим	Regions and AR Crimea	Top-level regions
K	CitySpecial [Settlements]	Міста зі спец. статусом	Cities with special status	Treated as both Region & Settlement
P	District	Райони в областях та АР Крим	Districts in regions and AR Crimea	District of an oblast
H	Community	Територіальні громади	Territorial communities	Аssociation of small settlements
M	City [Settlements]	Міста	Сities	Basically, it's about second-tier cities.
X	Urban [Settlements]	Селища	Urbans*	Urban-type settlement category folded
C	Village [Settlements]	Села	Villages	Common village type
B	DistrictCity [Settlements]	Райони в містах	City districts	Urban district (e.g. "Святошинський")

Note: The older "Селища міського типу" (category T) has been deprecated and merged into category X.

🧑‍💻 Basic Usage

Initializing the API:

import { GeoAPI } from "ua-geo-set";

const geo = new GeoAPI();

Regions:

// Get all regions (categories O + K)
const regions = geo.getAllRegions();

// Find a specific region by UA-code
const vinnitsa = geo.getRegionById("UA02000000000045678");
console.log(vinnitsa?.name); // "Вінницька область"

// Find "Kyiv" (a special-status city) in regions
const kyivRegion = regions.find(r => r.name === "Київ");
console.log(kyivRegion?.id); // "UA80000000000093317"

Each Region object has:

  interface Region {
  id: string;                     // UA-code, e.g. "UA02000000000045678"
  name: string;                   // e.g. "Вінницька область" or "Київ"
  category: CategoryBase;         // "Region" or "CitySpecial"
  nameFull: string;               // e.g. "Вінницька область"
  districts: RegionChild[];
}

Districts:

// Get all region's districts
const allRegionDistricts = geo.getAllRegionDistricts();

// Get all cities districts
const allCitiesDistricts = geo.getAllCityDistricts();

// Get Any District by id
const district = geo.getDistrictById("UA80000000000875983"); // "Святошинський р-н" міста Київ


// Get only districts belonging to a given region
const vinnytsiaDistricts = geo.getAllRegionDistricts("UA05000000000010236");
vinnytsiaDistricts.forEach(d => console.log(d.name));

// For a city district ("B"), regionId will be the city-code
const kyivDistricts = geo.getAllCityDistricts("UA80000000000093317");
console.log(kyivDistricts.map(d => d.name));

Each District:

interface District {
  id: string;                      // UA-code of the district
  name: string;                    // e.g. "Бахчисарайський" or "Святошинський"
  category: CategoryBase;          // "District" or "DistrictCity"
  nameFull: string;                // e.g. "Бахчисарайський район"
  regionId: string;                // UA-code of parent (oblast or city)
  communities: DistrictChild}[];
}

Communities:

// Get all communities
const communities = geo.getAllCommunities();

// Filter by district
const nikopolsDistrictkaComms = geo.getAllCommunities("UA12080000000023578");

// Search by partial name
const nikop = geo.searchCommunitiesByName("Нікоп");
console.log(nikop.map(c => c.name)); // ["Нікопольська"]

Each Community:

interface Community {
  id: string;                     // UA-code
  name: string;                   // e.g. "Андріївська"
  category: CategoryBase;         // "Community"
  nameFull: string;               // "Андріївська територіальна громада"
  districtId: string;             // UA-code of parent district
  regionId: string;               // UA-code of parent oblast or city
  settlements: CommunityChild[];
}

Settlements:

// Get all settlements
const allSettlements = geo.getAllSettlements();

// Filter by region, district, or community
const poltavasSettlements = geo.getAllSettlements({ regionId: "UA53000000000028050" });
const bahchisarayskiyDistrictSettlements = geo.getAllSettlements({ districtId: "UA01020000000022387" });
const nikopolskaComms = geo.getAllSettlements({ communityId: "UA12080050000062712" });

// Search by partial name
const barSettlements = geo.searchSettlementsByName("Бар");
console.log(barSettlements.map(s => s.name)); 

// Fetch a single settlement by UA-code
const andriyivka = geo.getSettlementById("UA12140250020066759");
console.log(andriyivka?.name); // село "Андріївка"

Each Settlement:

interface Settlement {
  id: string;               // UA-code
  name: string;             // e.g. "Андріївка", "Київ"
  category: string;         // "City" | "CitySpecial" | "Urban" | "Village" | 
  nameFull: string;         // e.g. "Андріївка село"
  parentId: string | null;  // UA-code of parent (community or district)
  parentType:               // one of:
    | KattogStructureType.Community 
    | KattogStructureType.District 
    | null;
  regionId: string | null;  // UA-code of oblast or city for urban districts
}

Search Examples:

// [Temp solution] Search regions by name
const region = geo.getAllRegions().find((r) => r.name === cityName);
getAllDistricts
// Search districts by name
const district = geo.getAllRegions().find((r) => r.name === regionDistrictName);
console.log(barDistricts.map(d => d.name)); // ["Барський район"]

// Search communities by name
const andriyivkaComms = geo.searchCommunitiesByName("Андріївська");
console.log(andriyivkaComms.map(c => c.name)); // ["Андріївська територіальна громада"]

// Search settlements by name
const barSettlements = geo.searchSettlementsByName("Бар");
console.log(barSettlements.map(s => s.name)); // ["Бар", "Барок", "Барське", ...]

🌳 Folder Structure

ua-geo-set/
├─ data/
│ ├─ kattog.json # Compact, index-based JSON (KATOTTG 2024)
│ └─ raw-kattog.json # Original (partially cleaned) JSON (KATOTTG 2024)
├─ src/
│ ├─ lib/
│ │ ├─ enums.ts # CategoryCode, CategoryBase, KattogStructureType
│ │ ├─ types.ts # RawItem, RawOptimizedData, Region, etc.
│ │ ├─ normalize.ts # normalizeRegion/District/Community/Settlement
│ │ ├─ mappers.ts # Mapping CategoryCode → suffix/postfix
│ │ └─ geo-api.ts # GeoAPI class
│ └─ index.ts # (optional) re-export of GeoAPI
├─ tests/
│ └─ geo-api.test.ts # Jest tests for GeoAPI
├─ scripts/
│ └─ optimize-kattog.ts # Script to generate kattog.json from raw-kattog.json
├─ README.md
├─ CHANGELOG.md
├─ package.json
└─ tsconfig.json

CHANGELOG

Please see CHANGELOG.md for a detailed list of changes and version history.

License

This project is licensed under the MIT License. See LICENSE for details.