Format Response dan Wrapper `data`/`meta`

Semua endpoint di bawah base URL /v2 mengembalikan JSON dengan amplop yang sama: objek data berisi payload sebenarnya, objek meta berisi keterangan berkas. Bentuk ini tidak berbeda antar endpoint karena seluruh berkas JSON ditulis lewat satu fungsi pembungkus. README.md:55-74¹

type genMeta struct {
	UpdatedAt string `json:"updated_at"`
	Level     int    `json:"level"`
}

func genResponse(data any, level int) map[string]any {
	return map[string]any{
		"data": data,
		"meta": genMeta{UpdatedAt: time.Now().UTC().Format("2006-01-02"), Level: level},
	}
}

Fungsi genResponse mencetak meta.updated_at sebagai tanggal YYYY-MM-DD dari jam UTC saat berkas ditulis, dan meneruskan level sebagai argumen pemanggil. tools/generate_static_api.go:150-160²

Nilai data bisa berupa objek tunggal (endpoint detail) atau array (endpoint daftar). Dua struct yang menentukan bentuknya adalah genPlace untuk objek dan genShortItem untuk item daftar; pada keduanya field has_path dideklarasikan tanpa omitempty, sehingga selalu muncul sebagai true atau false. tools/generate_static_api.go:100-123³

Level payload dan transisinya

meta.level menandai kedalaman data pada berkas itu. Nilainya bukan turunan dari id di dalam data, melainkan angka yang dikirim pemanggil genResponse. Akibatnya satu berkas daftar bisa berlevel berbeda dari id yang dikandungnya: regencies/32.json berisi daftar kab/kota tetapi tetap berlevel 2. tools/generate_static_api.go:241-245⁴

stateDiagram-v2
    [*] --> L0
    L0: level 0 stats.json dan missings.json
    L0 --> L1: provinces.json
    L1: level 1 provinces dan provinces/32.json
    L1 --> L2: regencies/32.json
    L2: level 2 regencies dan regencies/32.73.json
    L2 --> L3: districts/32.73.json
    L3: level 3 districts dan districts/32.73.01.json
    L3 --> L4: villages/32.73.01.json
    L4: level 4 villages dan postal-codes
    L4 --> [*]
    style L0 fill:#8b5cf6,color:#fff
    style L1 fill:#2d7d46,color:#fff
    style L2 fill:#2d7d46,color:#fff
    style L3 fill:#2d7d46,color:#fff
    style L4 fill:#2d7d46,color:#fff
%% fig: Transisi level payload antar berkas JSON
%% desc: Setiap turun satu tingkat hirarki, pemanggil genResponse menaikkan angka level dari 0 sampai 4; stats.json dan missings.json berada di level 0.

Contoh nyata untuk paths/32.json memperlihatkan meta.level bernilai 1 karena id 32 tidak memuat titik. web/src/components/api/apiSpec.ts:631-644¹⁰

meta.updated_at dan meta.generated_at

Dokumentasi menyebut dua nama field: meta.updated_at pada contoh amplop dan meta.generated_at (RFC3339) pada keterangan field. README.md:55-74¹ SKILL.md:21-35¹¹

Di dalam kode Go, generated_at hanya pernah muncul sebagai argumen delete: setiap tahap patch menghapus field itu lalu menimpa updated_at dengan tanggal hari patch. tools/add_has_path.go:172-176¹² Tahap pembaruan koordinat melakukan hal yang sama pada berkas detail dan berkas daftar. tools/generate_boundaries.go:606-609¹³ Tahap hitung ukuran berkas juga menimpa updated_at di stats.json. tools/update_stats.go:128-129¹⁴

Konsekuensinya, berkas hasil pipeline membawa updated_at berupa tanggal, bukan timestamp RFC3339 penuh. meta.updated_at adalah tanggal pemrosesan terakhir, bukan tanggal data hulu: nilai itu bergeser walau isi wilayah tidak berubah, setiap kali salah satu tahap patch menyentuh berkas. tools/add_has_path.go:172-176¹²

⚠️ Jangan memakai meta.updated_at sebagai penanda versi data. Field ini ditulis ulang oleh add-has-path, generate-boundaries, dan update-stats di setiap kali jalan, jadi tanggal berubah tanpa perubahan wilayah. tools/update_stats.go:128-129¹⁴

has_path dan has_latlng

Kedua bendera menjawab pertanyaan berbeda. has_path menempel pada setiap objek wilayah di endpoint provinsi sampai desa, sedangkan has_latlng hanya ada di missings.json sebagai hasil evaluasi. tools/generate_missings.go:31-36¹⁵

graph LR
    paths["api/paths/*.json"] --> set["buildHasPathSet"]
    set --> patch["patchFileHasPath"]
    patch --> item["genPlace.has_path"]
    latlng["lat + lng pada berkas wilayah"] --> eval["hasLatLngFromMap"]
    eval --> mjson["missings.json: has_latlng"]
    style paths fill:#336791,color:#fff
    style set fill:#f59e0b,color:#000
    style patch fill:#8b5cf6,color:#fff
    style item fill:#2d7d46,color:#fff
    style latlng fill:#336791,color:#fff
    style eval fill:#f59e0b,color:#000
    style mjson fill:#8b5cf6,color:#fff

%% fig: Asal nilai has_path dan has_latlng %% desc: has_path disalin dari daftar nama berkas di direktori paths, sedangkan has_latlng dihitung dari ada tidaknya lat dan lng di berkas wilayah.

buildHasPathSet membaca nama berkas di direktori paths, membuang sufiks .json dengan strings.TrimSuffix, dan menjadikan sisanya kunci himpunan. tools/add_has_path.go:110-126¹⁶ patchFileHasPath lalu menulis m["has_path"] = hasPathSet[id] untuk setiap item array, atau v["has_path"] = hasPathSet[id] untuk objek tunggal. tools/add_has_path.go:144-170¹⁷ Artinya has_path mencerminkan ada tidaknya berkas api/paths/{id}.json pada saat patch dijalankan, bukan hasil pembacaan geometri di dalam berkas itu.

⚠️ Menjalankan generate-boundaries dengan -limit memotong daftar target sebelum diproses, sehingga hanya sebagian api/paths/*.json yang tertulis dan sisanya mendapat has_path: false di tahap patch berikutnya. tools/generate_boundaries.go:197-200¹⁸

has_latlng dihitung oleh hasLatLngFromMap: hasilnya false bila lat atau lng tidak ada atau bernilai null, dan juga false bila keduanya 0. tools/generate_missings.go:228-247¹⁹ Entry hanya dimasukkan ke daftar bila has_path atau has_latlng bernilai false. tools/generate_missings.go:109-115²⁰ Rincian isi dan arti summary.by_level dibahas di Kelengkapan Data dan missings.json.

Pemakaian praktisnya: periksa has_path lebih dulu, baru fetch paths/{id}.json, supaya tidak menerima 404. SKILL.md:149-152²¹

Bentuk yang menyimpang dari amplop standar

Dua berkas menambah kunci di luar data dan meta:

• missings.json menambahkan summary di akar objek, berisi total_missing, total_missing_path, total_missing_latlng, total_missing_both, dan by_level yang dihitung per level id. tools/generate_missings.go:159-163⁶ Hitungan per level itu memakai genLevelCount(m.ID) dengan province untuk 0 titik sampai village untuk 3 titik. tools/generate_missings.go:125-149²²
• paths/{code}.json memakai data berisi objek {id, path} tanpa name, dan level dihitung dari jumlah titik pada id ditambah satu. tools/generate_boundaries.go:242-249²³

Contoh keluaran missings.json yang menampilkan summary di samping data dan meta dapat dilihat pada spesifikasi di website. web/src/components/api/apiSpec.ts:684-699²⁴ Bentuk objek stats.json mengikuti pola yang sama: seluruh total ada di dalam data, dengan meta.level 0. web/src/components/api/apiSpec.ts:57-77²⁵ Untuk daftar endpoint beserta payload masing-masing, lihat Referensi Endpoint.