Referensi Endpoint

Semua endpoint berada di bawah satu base URL, https://www.emsifa.com/api-wilayah-indonesia/v2 README.md:9¹. Method-nya selalu GET dan tidak ada auth README.md:80². Katalog 12 path yang sama ditulis di tiga tempat: tabel README untuk manusia README.md:82-95, tabel SKILL.md untuk dibaca AI agent SKILL.md:78-93, dan kontrak openapi.yml web/public/openapi.yml:19-21. Website merender katalog ini dari array apiEndpoints web/src/components/api/apiSpec.ts:24-26.

Katalog endpoint

Pemetaan berkas ke meta.level dikerjakan satu fungsi, phaseA tools/generate_static_api.go:241-288¹⁹. Pengecualian ada di /paths/: levelnya genLevelCount(kode)+1, yaitu jumlah titik pada kode ditambah satu tools/generate_static_api.go:346²⁰, sementara genLevelCount sendiri hanya menghitung titik tools/generate_static_api.go:164²¹. /stats.json selalu ditulis dengan level 0 tools/generate_static_api.go:417²².

/stats.json dirakit dua tahap. writeStats menulis delapan kunci dasar (total_provinces sampai total_area) tools/generate_static_api.go:407-416²³, lalu perintah update-stats menambahkan total_endpoints, total_filesize, dan total_disk_usage tools/update_stats.go:121²⁴. Nilai total_paths berasal dari jumlah berkas di api/paths/, jadi ikut berubah tiap generate. Angka yang dipublikasikan saat ini: 38 provinsi, 514 kab/kota, 7285 kecamatan, 83762 desa, 10632 kode pos, 91238 path, dan 201309 endpoint README.md:13-22²⁵.

Alur request dari provinsi ke desa

Urutan yang dianjurkan: provinces → regencies/{prov} → districts/{reg} → villages/{dist}, selalu memakai kode asli dari response sebelumnya SKILL.md:210²⁶. Tiap langkah hanya membaca satu berkas statis, tanpa server yang menyusun join.

sequenceDiagram
  participant C as Client
  participant H as Static hosting
  participant P as "/provinces.json"
  participant R as "/regencies/{id}.json"
  participant D as "/districts/{id}.json"
  participant V as "/villages/{id}.json"
  participant B as "/paths/{id}.json"
  C->>H: GET /provinces.json
  H-->>C: daftar provinsi + has_path
  C->>H: GET /regencies/32.json
  H-->>C: kab/kota Jawa Barat
  C->>H: GET /districts/32.73.json
  H-->>C: kecamatan + lat/lng
  C->>H: GET /villages/32.73.01.json
  H-->>C: desa + postal_code
  alt has_path sama dengan true
    C->>H: GET /paths/32.73.01.1001.json
    H-->>C: id + path
  else has_path sama dengan false
    C->>C: lewati polygon
  end
%% fig: Rangkaian request dari provinsi ke detail desa
%% desc: Client menelusuri empat tingkat lewat kode dari response sebelumnya, lalu hanya meminta polygon bila has_path bernilai true.

Empat request pertama selalu berupa daftar, dan detail satu wilayah diambil dari endpoint yang sama dengan kode lengkap: regencies/32.73.json, districts/32.73.01.json, villages/32.73.01.1001.json. Detail endpoint menyisipkan parent lewat genParentPlace tools/generate_static_api.go:143-148²⁷, sehingga client tidak perlu memanggil ulang level di atasnya.

Bentuk data per level

Generator memakai dua struct berbeda supaya berkas daftar tetap kecil: genPlace untuk provinsi dan kab/kota, genShortItem untuk daftar kecamatan dan desa. add-has-path menyatukan keduanya dengan menambal satu field tambahan.

graph LR
  W["wilayah.csv"] --> PA["phaseA"]
  L12["wilayah_level_1_2.csv"] --> PB["phaseB"]
  PA --> SHORT["genShortItem: id, name, postal_code"]
  PB --> RICH["genPlace: capital, lat, lng, elv, tz, population, total_area"]
  PB --> PATHS["api/paths"]
  SHORT --> HP["add-has-path"]
  RICH --> HP
  PATHS --> HP
  HP --> OUT["api/*.json"]
  OUT --> MISS["api/missings.json"]
  style PA fill:#f59e0b,color:#000
  style PB fill:#f59e0b,color:#000
  style SHORT fill:#8b5cf6,color:#fff
  style RICH fill:#8b5cf6,color:#fff
  style PATHS fill:#8b5cf6,color:#fff
  style HP fill:#2d7d46,color:#fff
  style OUT fill:#336791,color:#fff
  style MISS fill:#dc2626,color:#fff
%% fig: Dari CSV ke bentuk data per level
%% desc: phaseA membangun daftar compact, phaseB memperkaya level 1 dan 2 serta menulis polygon, lalu add-has-path menambal has_path sebelum missings.json dihitung.

Definisi genPlace ada di tools/generate_static_api.go:107-123²⁸ dan genShortItem di tools/generate_static_api.go:100-105²⁹. lat/lng pada daftar kecamatan dan desa tidak berasal dari genShortItem; updateListLatLng menambalnya per item dari peta koordinat tools/generate_boundaries.go:618-650. Field has_path diisi add-has-path, yang lebih dulu memindai isi api/paths/ menjadi himpunan kode tools/add_has_path.go:110-127, lalu menambal setiap objek tools/add_has_path.go:144-170.

⚠️ has_path di objek parent tidak bisa dipercaya. Field HasPath ditulis tanpa omitempty tools/generate_static_api.go:118³³, sedangkan genParentPlace hanya mengisi ID dan Name tools/generate_static_api.go:143-148²⁷. Patch add-has-path cuma menyentuh objek data paling atas tools/add_has_path.go:144-170³², jadi parent selalu membawa "has_path": false. Contoh playground yang menampilkan has_path: true di dalam province web/src/components/api/apiSpec.ts:305-309³⁴ tidak dihasilkan generator. Untuk parent, pakai has_path dari item aslinya di provinces.json atau /paths/{id}.json.

⚠️ Nama kunci meta berbeda antara dokumentasi dan payload. SKILL.md mendokumentasikan meta.generated_at berformat RFC3339 SKILL.md:24-31³⁵, sementara genResponse menulis updated_at bertanggal 2006-01-02 tools/generate_static_api.go:150-160³⁶. add-has-path menghapus generated_at lalu menulis updated_at tools/add_has_path.go:172-176³⁷, jadi response yang disajikan hanya memuat updated_at. Jangan parsing generated_at.

Endpoint khusus

/paths/{region_id}.json hanya diambil kalau has_path bernilai true. Payload-nya { id, path } dengan path berupa array titik koordinat, dan berkasnya ditulis compact lewat writeGenJSONCompact tools/generate_static_api.go:346²⁰. Bentuk ring dan cara menggambar polygon dibahas di Polygon dan Boundary.

/missings.json menaruh summary di root response, bukan di dalam meta tools/generate_missings.go:159-163³⁸. Arti tiap kunci summary dan cara memakainya ada di Kelengkapan Data dan missings.json; bentuk wrapper data/meta di Format Response dan Wrapper data/meta; aturan kode dan level di Skema Kode dan Level Wilayah.

/postal-codes/{postal_code}.json dibuat satu berkas per kode pos dengan level 4 tools/generate_static_api.go:288³⁹. Setiap desa di dalamnya membawa province, regency, dan district web/src/components/api/apiSpec.ts:569-597¹⁶, jadi satu request sudah cukup untuk tahu lokasi lengkap sebuah kode pos. Contoh request lengkap untuk semua endpoint, termasuk potongan curl, fetch, dan axios, dirender playground dari apiSpec.ts — lihat Website dan Playground.