KodeNIK

Official Indonesian Administrative National Identity Number (Nomor Induk Kependudukan — NIK) subdivision database.

This repository provides structured regional administrative codes for all 38 provinces, 514 regencies/cities (416 Kabupaten and 98 Kota), and 7,277 districts (Kecamatan) across Indonesia, directly corresponding to the geographic prefix of Indonesian identity cards.

Indonesian NIK Structure

The 16-digit Indonesian NIK consists of three segments:

[ P P ][ K K ][ C C ][ D D ][ M M ][ Y Y ][ S S S S ]
  1 2    3 4    5 6    7 8    9 10  11 12   13 14 15 16
|-- Geographic Code -|----- Date of Birth -----|-- Serial |

• Digits 1–2 (PP): Province code (kode_provinsi), 11 through 96.
• Digits 3–4 (KK): Regency or City code (kode_kabkota):
  • 01–69: Kabupaten (Regency)
  • 71–99: Kota (City)
• Digits 5–6 (CC): District code (kode_kecamatan), 01 through 55.
• Digits 7–12 (DDMMYY): Date of birth:
  • Males: day 01–31.
  • Females: day $+ 40$ (41–71).
  • Month: 01–12.
  • Year: 2-digit birth year 00–99.
• Digits 13–16 (SSSS): 4-digit sequential issue number.

The first 6 digits (PPKKCC) form the unique administrative district prefix verified by this dataset.

Repository Contents

Installation & Quick Start

Node.js / TypeScript (npm)

npm install kodenik

import { lookupNik, validateNik, extractNikInfo } from 'kodenik';

// 1. Instant O(1) prefix or full NIK resolution
const district = lookupNik('3174070101900001');
console.log(district);
// {
//   kode_provinsi: "31",
//   nama_provinsi: "DKI Jakarta",
//   kode_kabkota: "74",
//   nama_kabkota: "Kota Jakarta Selatan",
//   kode_kecamatan: "07",
//   nama_kecamatan: "Kebayoran Baru"
// }

// 2. Validate NIK syntax, birthdate bounds, and regional existence
const validation = validateNik('3174071508950001');
console.log(validation.valid); // true

// 3. Decode birth date, gender, and regional metadata
const info = extractNikInfo('3174075508950001');
console.log(info?.gender); // "female" (day 15 + 40 = 55)
console.log(info?.birthDate); // { day: 15, month: 8, yearTwoDigit: 95 }

Python (pip)

pip install kodenik

import kodenik

# 1. Instant O(1) lookup
district = kodenik.lookup_nik("317407")
print(district["nama_kecamatan"])  # Kebayoran Baru

# 2. Validate NIK
res = kodenik.validate_nik("3174071508950001")
print(res["valid"])  # True

# 3. Extract demographic and regional data
info = kodenik.extract_nik_info("3174075508950001")
print(info["gender"])      # female
print(info["birth_date"])  # {'day': 15, 'month': 8, 'year_two_digit': 95}

CLI Querying with jq

# Query district details for prefix 110507
jq -r '.districts["110507"] | "\(.nama_provinsi) > \(.nama_kabkota) > \(.nama_kecamatan)"' KodeNIK.flat.json

Development & Testing

All validation suites require zero external dependencies:

# Run Python integrity tests
python3 -m unittest discover -s test -p "test_*.py"

# Run Node.js native tests
node --test test/validate.test.mjs

# Validate JSON syntax
python3 -m json.tool KodeNIK.json > /dev/null

# Rebuild flat lookup artifact
python3 scripts/generate-flat.py

Data Governance & Versioning

• Scheme: Calendar Versioning (YYYY.MM.DD).
• Sources: Indonesian Ministry of Home Affairs (Kementerian Dalam Negeri / Kemendagri), Direktorat Jenderal Kependudukan dan Pencatatan Sipil (Ditjen Dukcapil), and Badan Pusat Statistik (BPS).

License

MIT License. Copyright (c) 2024 faizath <github.com/faizath>.