# kodepos-api

REST API publik dan gratis untuk kode pos dan wilayah administrasi Indonesia, tanpa API key.
Sumber kode pos merujuk direktori resmi [Pos Indonesia](https://kodepos.posindonesia.co.id/).

## Data

- 38 provinsi, 514 kabupaten/kota, 7.277 kecamatan, 85.595 desa/kelurahan beserta kode pos.
- Setiap respons desa membawa hirarki desa, kecamatan, kabupaten, provinsi.

## Aturan pakai

- Rate limit 100 request per menit per IP (429 + Retry-After bila terlampaui).
- Pagination: ?page= (default 1), ?limit= (default 50, maks 100).
- Respons list: {data, meta:{page,limit,total}}.

## Endpoint

- [GET /health](https://kodepos.api.hizb.or.id/health) — status server.
- [GET /api/v1/provinces](https://kodepos.api.hizb.or.id/api/v1/provinces) — daftar provinsi (?q=, ?page=, ?limit=).
- [GET /api/v1/regencies](https://kodepos.api.hizb.or.id/api/v1/regencies?province_id=1) — daftar kabupaten/kota (?province_id=, ?province= nama, ?q=).
- [GET /api/v1/districts](https://kodepos.api.hizb.or.id/api/v1/districts?regency_id=1) — daftar kecamatan (?regency_id=, ?regency= nama, ?q=).
- [GET /api/v1/villages](https://kodepos.api.hizb.or.id/api/v1/villages?province=Jakarta&regency=Pusat&district=Gambir&q=Gambir) — daftar desa (?district_id=, ?district=, ?regency=, ?province=, ?postal_code=, ?q=).
- [GET /api/v1/postal-codes/10110](https://kodepos.api.hizb.or.id/api/v1/postal-codes/10110) — cari desa dari kode pos.
- [GET /api/v1/villages/1](https://kodepos.api.hizb.or.id/api/v1/villages/1) — contoh detail desa (id, district_id, regency_id, province_id + nama hirarki).
- [Unduh dump CSV resmi](https://kodepos.api.hizb.or.id/download/kodepos.csv) — seluruh 85.595 desa sekaligus (9 kolom). Untuk kebutuhan massal, pakai jalur ini, bukan scraping halaman.

## Dokumen

- [Dokumentasi interaktif](https://kodepos.api.hizb.or.id/docs)
- [Spesifikasi OpenAPI](https://kodepos.api.hizb.or.id/openapi.json)
- [Peta situs](https://kodepos.api.hizb.or.id/sitemap.xml)
- Koreksi data: [developer@hizb.or.id](mailto:developer@hizb.or.id)