Ringkasan Proyek

emsifa/api-wilayah-indonesia adalah repository yang men-generate (REST) API statis berisi data wilayah Indonesia: provinsi, kabupaten/kota, kecamatan, desa/kelurahan, kode pos, dan boundary polygon — lengkap dengan cara mendeploy hasilnya ke static hosting seperti GitHub Pages, Cloudflare Pages, Vercel, atau Nginx. Karena endpoint-nya hanya berkas JSON statis, tidak ada server, tidak ada API key, dan tidak ada rate limit: pemakaian cukup lewat fetch ke base URL https://www.emsifa.com/api-wilayah-indonesia/v2 — README.md:3-9¹

Isi api/ tidak ditulis tangan. Perintah Go di tools/ membacakan berkas csv di data/ lalu menulis ribuan berkas JSON ke api/. Toolchain mengikuti module data-wilayah dengan go 1.25 — go.mod:1-3² — dan seluruh subperintah dijalankan lewat satu binary tools/main.go — tools/main.go:8-23³ — README.md:29-42⁴

Angka terbaru dari GET /stats.json

stats.json adalah satu-satunya endpoint yang merangkum seluruh isi api/. Angka di bawah dikutip apa adanya dari README pada commit ini — README.md:11-23⁵ — README.md:109-130⁶

total_provinces sampai total_paths dihitung langsung oleh writeStats dari peta regenciesByProv, districtsByReg, villagesByDist, dan postalToNew — tools/generate_static_api.go:407-417⁷. Dua field terakhir (total_endpoints, total_filesize, beserta varian _human dan total_disk_usage) bukan hasil writeStats, melainkan tambalan go run ./tools update-stats yang menyusuri seluruh berkas .json di api/ — tools/update_stats.go:1-14⁸

Wrapper response selalu sama di semua endpoint: {"data": ..., "meta": {"updated_at", "level"}}, dengan meta.level bernilai 0 untuk stats, 1 untuk provinsi, 2 untuk kab/kota, 3 untuk kecamatan, dan 4 untuk desa/kode pos. Bentuk ini dijelaskan lebih jauh di Format Response dan Wrapper data/meta.

Bagaimana masukan berubah menjadi api/

Diagram berikut memetakan tiga masukan data, rantai perintah yang mengolahnya, dan berkas keluaran yang akhirnya disalin ke direktori publish. Perhatikan bahwa setiap perintah menulis ke api/ yang sama, sehingga urutannya penting.

graph TD
  SQL["SQL dump cahyadsn: wilayah, wilayah_level_1_2, wilayah_kodepos"] --> EXT["extract-csv"]
  EXT --> CSV["data/*.csv"]
  CSV --> GEN["generate-static-api (phaseA + phaseB)"]
  GEN --> API["api/: provinces, regencies, districts, villages, postal-codes"]
  ZIP[".cache/wilayah_boundaries.zip"] --> GB["generate-boundaries"]
  GB --> PATHS["api/paths/*.json"]
  PATHS --> AHP["add-has-path"]
  AHP --> API
  AHP --> GM["generate-missings"]
  GM --> MISS["api/missings.json"]
  API --> US["update-stats"]
  US --> STATS["api/stats.json"]
  API --> PUB["deploy/v2 + web/dist ke branch gh-pages"]
  style CSV fill:#336791,color:#fff
  style API fill:#8b5cf6,color:#fff
  style PATHS fill:#8b5cf6,color:#fff
  style MISS fill:#8b5cf6,color:#fff
  style STATS fill:#2d7d46,color:#fff
  style PUB fill:#2d7d46,color:#fff
  style EXT fill:#f59e0b,color:#000
  style GEN fill:#f59e0b,color:#000
  style GB fill:#f59e0b,color:#000
  style AHP fill:#f59e0b,color:#000
  style GM fill:#f59e0b,color:#000
  style US fill:#f59e0b,color:#000
%% fig: Alur masukan, generate, dan keluaran API
%% desc: CSV dan arsip boundary diproses berurutan oleh perintah di tools/, lalu JSON yang dihasilkan disalin ke direktori deploy.

generate-static-api sengaja dipecah dua fase agar kolom geometry tidak pernah ditahan untuk semua wilayah sekaligus: phase A men-stream wilayah.csv dan membaca wilayah_kodepos.csv untuk semua berkas dasar, phase B men-stream wilayah_level_1_2.csv untuk memperkaya provinsi dan kab/kota sekaligus menulis /paths/ — tools/generate_static_api.go:41-87⁹. Enam subperintah beserta flag bawaannya tercantum di usage tools/main.go — tools/main.go:8-23³

Rantai yang sama dijalankan workflow .github/workflows/deploy.yml pada setiap push ke master/v2, tiap workflow_dispatch, dan tiap cron mingguan 0 0 * * 0 — .github/workflows/deploy.yml:1-7¹⁰ — .github/workflows/deploy.yml:37-49¹¹. Langkah per langkahnya dibahas di Pipeline Generate dengan Go Tools dan Deploy dan CI.

Dua konsekuensi yang mudah terlewat

⚠️ api/ dan data/ keduanya masuk .gitignore — .gitignore:6-7. Clone bersih dari repository tidak berisi satu pun berkas JSON hasil generate, jadi fetch ke path lokal akan gagal. Untuk mendapatkannya, jalankan rantai perintah di atas atau ambil langsung dari base URL produksi.

⚠️ Direktori publish dirakit dengan cp -r, bukan sinkronisasi: web/dist disalin ke akar deploy/, lalu api/* disalin ke deploy/v2/ — .github/workflows/deploy.yml:92-98¹². Berkas lama di branch gh-pages dipertahankan lewat keep_files: true, sehingga berkas yang sudah tidak di-generate tetap bisa tersaji — .github/workflows/deploy.yml:106-115¹³.

Peta isi dokumentasi

Halaman ini hanya memberi gambaran umum. Topik yang lebih rinci ada di halaman berikut.