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),11through96. - 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),01through55. - 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.
- Males: day
- 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
| Path | Purpose |
|---|---|
KodeNIK.json |
Primary 3-tier hierarchical JSON database (Province $\rightarrow$ KabKota $\rightarrow$ Kecamatan). |
KodeNIK.flat.json |
Pre-indexed key-value dictionary keyed by 6-digit NIK prefix for $O(1)$ lookups. |
schema/kodenik.schema.json |
JSON Schema (Draft-07) defining structure and 2-digit code regex constraints. |
types/index.d.ts |
Complete TypeScript type definitions. |
scripts/generate-flat.py |
Generator script to compile KodeNIK.flat.json from KodeNIK.json. |
test/test_integrity.py |
Zero-dependency Python unittest data integrity test suite. |
test/validate.test.mjs |
Zero-dependency Node.js native test runner suite (node:test). |
.github/workflows/ci.yml |
GitHub Actions automated validation workflow. |
LICENSE |
MIT License. |
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>.
Metadata
Release files for kodenik 2024.3.6
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| kodenik-2024.3.6.tar.gz | 181.1 kB | Without provenance | Details for kodenik-2024.3.6.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| kodenik-2024.3.6-py3-none-any.whl | Python 3 | none | any | Details for kodenik-2024.3.6-py3-none-any.whl |
Total release size: 374.4 kB
Release files / kodenik-2024.3.6.tar.gz
| Download URL | kodenik-2024.3.6.tar.gz |
|---|---|
| Size | 181.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9cb55491f1de5bc977dfb8028ca0efa9ca25adc25c1eebe91425dbb3954afbb3
|
|
BLAKE2b-256 checksum How to use checksums |
71b81fd11d480f8ee1b1a292d978340e3f07100faf43a31f1c5aaad2bb2d0f33
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.4
|
Release files / kodenik-2024.3.6-py3-none-any.whl
| Download URL | kodenik-2024.3.6-py3-none-any.whl |
|---|---|
| Size | 193.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
6254b55cc73b946f29aef1b87da2f638fbad5faabc2d585539bd61108d9ea118
|
|
BLAKE2b-256 checksum How to use checksums |
3e46d6abf4dd02408a2b5c0819664703a98ed492690a80dd1c9ed6d33d623424
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.4
|
Security for kodenik 2024.3.6
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.