{
    "openapi": "3.0.3",
    "info": {
        "title": "API Wilayah Indonesia 2026",
        "description": "Dokumentasi resmi REST API Wilayah Administratif Republik Indonesia edisi 2026. Mencakup data terkini 38 Provinsi (termasuk Daerah Khusus Jakarta dan 4 DOB Papua: Papua Selatan, Papua Tengah, Papua Pegunungan, dan Papua Barat Daya dengan kode resmi 96), 514 Kabupaten/Kota, 7.277 Kecamatan, dan 83.763 Kelurahan/Desa beserta kode pos.\n",
        "version": "3.2.0",
        "contact": {
            "name": "Roedy Rustam",
            "email": "roedyrustam@gmail.com",
            "url": "https://github.com/roedyrustam/API-Wilayah-2024"
        },
        "license": {
            "name": "MIT",
            "url": "https://github.com/roedyrustam/API-Wilayah-2024/blob/main/LICENSE"
        }
    },
    "servers": [
        {
            "url": "/api",
            "description": "Production Server (apiwilayah2026.vercel.app)"
        },
        {
            "url": "https://apiwilayah2026.vercel.app/api",
            "description": "Production Public HTTPS API"
        },
        {
            "url": "http://127.0.0.1:8000/api",
            "description": "Local Development Server (127.0.0.1:8000)"
        }
    ],
    "paths": {
        "/v1/provinsi": {
            "get": {
                "summary": "Daftar Provinsi",
                "description": "Mengambil seluruh data 38 provinsi di Indonesia dengan dukungan pencarian dan pagination.",
                "tags": [
                    "Provinsi"
                ],
                "parameters": [
                    {
                        "name": "search",
                        "in": "query",
                        "description": "Cari berdasarkan nama provinsi (contoh: Papua, Jawa, Jakarta)",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "code",
                        "in": "query",
                        "description": "Filter berdasarkan 2-digit kode provinsi (contoh: 11, 31, 96)",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "paginate",
                        "in": "query",
                        "description": "Set true untuk mengaktifkan pagination (default: false)",
                        "required": false,
                        "schema": {
                            "type": "boolean"
                        }
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "description": "Jumlah data per halaman jika paginate=true (maksimal 100)",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "default": 15
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Berhasil mengambil data provinsi",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "message": "Daftar seluruh provinsi berhasil diambil",
                                    "data": [
                                        {
                                            "id": 1,
                                            "name": "Aceh",
                                            "code": "11"
                                        },
                                        {
                                            "id": 26,
                                            "name": "Papua Barat Daya",
                                            "code": "96"
                                        }
                                    ],
                                    "meta": {
                                        "total": 38
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v1/provinsi/{id}": {
            "get": {
                "summary": "Detail Provinsi",
                "description": "Mengambil detail provinsi berdasarkan ID numerik atau 2-digit kode provinsi (contoh: 26 atau 96).",
                "tags": [
                    "Provinsi"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "description": "ID database atau kode provinsi (contoh: 26 atau 96)",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Detail provinsi ditemukan"
                    },
                    "404": {
                        "description": "Provinsi tidak ditemukan"
                    }
                }
            }
        },
        "/v1/provinsi/{id}/kabupaten": {
            "get": {
                "summary": "Daftar Kabupaten/Kota di Provinsi",
                "description": "Mengambil semua kabupaten/kota di bawah provinsi tertentu.",
                "tags": [
                    "Provinsi",
                    "Kabupaten"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "description": "ID atau kode provinsi (contoh: 26 atau 96)",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "search",
                        "in": "query",
                        "description": "Cari nama kabupaten/kota",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "type",
                        "in": "query",
                        "description": "Filter tipe (Kabupaten atau Kota)",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "Kabupaten",
                                "Kota"
                            ]
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Daftar kabupaten/kota berhasil diambil"
                    }
                }
            }
        },
        "/v1/kabupaten": {
            "get": {
                "summary": "Daftar Seluruh Kabupaten/Kota",
                "description": "Mengambil data 514 kabupaten/kota di Indonesia dengan filter provinsi, tipe, dan pencarian.",
                "tags": [
                    "Kabupaten"
                ],
                "parameters": [
                    {
                        "name": "provinsi_id",
                        "in": "query",
                        "description": "Filter berdasarkan ID provinsi induk",
                        "required": false,
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "search",
                        "in": "query",
                        "description": "Cari nama kabupaten/kota",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "full_code",
                        "in": "query",
                        "description": "Filter berdasarkan 4-digit full code (contoh: 9601, 3171)",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "type",
                        "in": "query",
                        "description": "Filter tipe wilayah",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "Kabupaten",
                                "Kota"
                            ]
                        }
                    },
                    {
                        "name": "paginate",
                        "in": "query",
                        "description": "Set true untuk pagination",
                        "required": false,
                        "schema": {
                            "type": "boolean"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Berhasil mengambil data kabupaten/kota"
                    }
                }
            }
        },
        "/v1/kabupaten/{id}": {
            "get": {
                "summary": "Detail Kabupaten/Kota",
                "description": "Mengambil detail kabupaten/kota berdasarkan ID atau 4-digit kode wilayah.",
                "tags": [
                    "Kabupaten"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "description": "ID atau full_code (contoh: 171 atau 9601)",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Detail kabupaten/kota ditemukan"
                    },
                    "404": {
                        "description": "Kabupaten/Kota tidak ditemukan"
                    }
                }
            }
        },
        "/v1/kabupaten/{id}/kecamatan": {
            "get": {
                "summary": "Daftar Kecamatan di Kabupaten/Kota",
                "description": "Mengambil seluruh kecamatan (distrik) di bawah kabupaten/kota tertentu.",
                "tags": [
                    "Kabupaten",
                    "Kecamatan"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "description": "ID atau full_code kabupaten (contoh: 171 atau 9601)",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "search",
                        "in": "query",
                        "description": "Cari nama kecamatan",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Daftar kecamatan berhasil diambil"
                    }
                }
            }
        },
        "/v1/kecamatan": {
            "get": {
                "summary": "Daftar Seluruh Kecamatan",
                "description": "Mengambil data kecamatan (distrik) di Indonesia dengan pagination (default: 25 per halaman).",
                "tags": [
                    "Kecamatan"
                ],
                "parameters": [
                    {
                        "name": "kabupaten_id",
                        "in": "query",
                        "description": "Filter berdasarkan ID kabupaten induk",
                        "required": false,
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "search",
                        "in": "query",
                        "description": "Cari nama kecamatan",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "full_code",
                        "in": "query",
                        "description": "Filter 6-digit full code (contoh: 960101)",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "description": "Jumlah data per halaman (default: 25)",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "default": 25
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Berhasil mengambil data kecamatan"
                    }
                }
            }
        },
        "/v1/kecamatan/{id}": {
            "get": {
                "summary": "Detail Kecamatan",
                "description": "Mengambil detail kecamatan berdasarkan ID atau 6-digit full_code.",
                "tags": [
                    "Kecamatan"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "description": "ID atau full_code (contoh: 960414)",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Detail kecamatan ditemukan"
                    },
                    "404": {
                        "description": "Kecamatan tidak ditemukan"
                    }
                }
            }
        },
        "/v1/kecamatan/{id}/kelurahan": {
            "get": {
                "summary": "Daftar Kelurahan/Desa di Kecamatan",
                "description": "Mengambil seluruh kelurahan/desa (kampung) di bawah kecamatan tertentu.",
                "tags": [
                    "Kecamatan",
                    "Kelurahan"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "description": "ID atau full_code kecamatan",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "search",
                        "in": "query",
                        "description": "Cari nama kelurahan/desa",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "pos_code",
                        "in": "query",
                        "description": "Filter kode pos",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Daftar kelurahan/desa berhasil diambil"
                    }
                }
            }
        },
        "/v1/kelurahan": {
            "get": {
                "summary": "Daftar Seluruh Kelurahan/Desa",
                "description": "Mengambil data kelurahan/desa di Indonesia dengan pencarian dan filter kode pos.",
                "tags": [
                    "Kelurahan"
                ],
                "parameters": [
                    {
                        "name": "kecamatan_id",
                        "in": "query",
                        "description": "Filter berdasarkan ID kecamatan induk",
                        "required": false,
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "search",
                        "in": "query",
                        "description": "Cari nama kelurahan/desa",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "full_code",
                        "in": "query",
                        "description": "Filter 10-digit full code (contoh: 9604032001)",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "pos_code",
                        "in": "query",
                        "description": "Filter berdasarkan 5-digit kode pos (contoh: 98379, 10110)",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "description": "Jumlah data per halaman (default: 25)",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "default": 25
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Berhasil mengambil data kelurahan/desa"
                    }
                }
            }
        },
        "/v1/kelurahan/{id}": {
            "get": {
                "summary": "Detail Kelurahan/Desa",
                "description": "Mengambil detail kelurahan/desa lengkap dengan hierarki relasi kecamatan, kabupaten, dan provinsi.",
                "tags": [
                    "Kelurahan"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "description": "ID atau 10-digit full_code",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Detail kelurahan/desa ditemukan"
                    },
                    "404": {
                        "description": "Kelurahan/Desa tidak ditemukan"
                    }
                }
            }
        },
        "/v1/search": {
            "get": {
                "summary": "Autocomplete / Pencarian Global",
                "description": "Mencari kata kunci secara simultan ke seluruh tingkat wilayah (Provinsi, Kabupaten/Kota, Kecamatan, dan Kelurahan/Desa/Kode Pos) dalam satu panggilan API.",
                "tags": [
                    "Pencarian Global"
                ],
                "parameters": [
                    {
                        "name": "q",
                        "in": "query",
                        "description": "Kata kunci pencarian (minimal 2 karakter, contoh: Sorong, 98415, Bandung)",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Hasil pencarian berhasil diambil"
                    },
                    "422": {
                        "description": "Parameter pencarian kurang dari 2 karakter"
                    }
                }
            }
        },
        "/v1/nearby": {
            "get": {
                "summary": "Pencarian Wilayah Terdekat (Geospatial / Radius)",
                "description": "Mencari wilayah administratif terdekat dalam radius kilometer tertentu dari titik koordinat GPS (Latitude & Longitude) menggunakan formula Haversine.",
                "tags": [
                    "Geospatial & Radius"
                ],
                "parameters": [
                    {
                        "name": "lat",
                        "in": "query",
                        "description": "Titik Latitude (-90 s/d 90, contoh -6.2088)",
                        "required": true,
                        "schema": {
                            "type": "number",
                            "format": "float"
                        }
                    },
                    {
                        "name": "lng",
                        "in": "query",
                        "description": "Titik Longitude (-180 s/d 180, contoh 106.8456)",
                        "required": true,
                        "schema": {
                            "type": "number",
                            "format": "float"
                        }
                    },
                    {
                        "name": "radius",
                        "in": "query",
                        "description": "Radius pencarian dalam kilometer (default 50 km)",
                        "required": false,
                        "schema": {
                            "type": "number",
                            "default": 50
                        }
                    },
                    {
                        "name": "level",
                        "in": "query",
                        "description": "Tingkat wilayah yang dicari (provinsi, kabupaten, kecamatan, kelurahan)",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "provinsi",
                                "kabupaten",
                                "kecamatan",
                                "kelurahan"
                            ],
                            "default": "provinsi"
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "description": "Batas jumlah hasil yang dikembalikan (default 10, max 50)",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "default": 10
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Daftar wilayah terdekat berhasil ditemukan beserta jarak (distance_km)"
                    },
                    "422": {
                        "description": "Parameter koordinat tidak valid atau di luar jangkauan"
                    }
                }
            }
        },
        "/v1/geojson/provinsi": {
            "get": {
                "summary": "GeoJSON RFC 7946 Seluruh Provinsi",
                "description": "Mengambil seluruh 38 provinsi dalam format standar RFC 7946 GeoJSON FeatureCollection untuk visualisasi peta Leaflet, Mapbox, dan QGIS.",
                "tags": [
                    "GeoJSON RFC 7946"
                ],
                "parameters": [
                    {
                        "name": "search",
                        "in": "query",
                        "description": "Filter nama provinsi",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "code",
                        "in": "query",
                        "description": "Filter kode provinsi",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "FeatureCollection GeoJSON provinsi berhasil diambil",
                        "content": {
                            "application/geo+json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v1/geojson/provinsi/{id}": {
            "get": {
                "summary": "GeoJSON Feature Detail Provinsi",
                "description": "Mengambil detail satu provinsi dalam format RFC 7946 GeoJSON Feature berdasarkan ID atau kode wilayah.",
                "tags": [
                    "GeoJSON RFC 7946"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "description": "ID atau kode provinsi (contoh: 26 atau 96)",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "GeoJSON Feature provinsi ditemukan"
                    },
                    "404": {
                        "description": "Provinsi tidak ditemukan"
                    }
                }
            }
        },
        "/v1/geojson/kabupaten": {
            "get": {
                "summary": "GeoJSON RFC 7946 Seluruh Kabupaten/Kota",
                "description": "Mengambil kabupaten/kota dalam format standar RFC 7946 GeoJSON FeatureCollection.",
                "tags": [
                    "GeoJSON RFC 7946"
                ],
                "parameters": [
                    {
                        "name": "provinsi_id",
                        "in": "query",
                        "description": "Filter ID provinsi induk",
                        "required": false,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "FeatureCollection GeoJSON kabupaten/kota berhasil diambil"
                    }
                }
            }
        },
        "/v1/export/{level}": {
            "get": {
                "summary": "Ekspor Master Data (CSV / JSON Stream)",
                "description": "Mengunduh langsung seluruh data wilayah per tingkat administratif dalam format file CSV spreadsheet (ber-BOM Excel UTF-8) atau JSON murni.",
                "tags": [
                    "Ekspor Data"
                ],
                "parameters": [
                    {
                        "name": "level",
                        "in": "path",
                        "description": "Tingkat wilayah (provinsi, kabupaten, kecamatan, kelurahan)",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "provinsi",
                                "kabupaten",
                                "kecamatan",
                                "kelurahan"
                            ]
                        }
                    },
                    {
                        "name": "format",
                        "in": "query",
                        "description": "Format file keluaran (csv atau json)",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "csv",
                                "json"
                            ],
                            "default": "csv"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Berkas unduhan CSV/JSON berhasil dialirkan (streaming)"
                    },
                    "404": {
                        "description": "Tingkat wilayah tidak valid"
                    }
                }
            }
        },
        "/v1/kodepos": {
            "get": {
                "summary": "Pencarian Kode Pos 5-Digit",
                "description": "Mencari daftar kode pos wilayah dan kelurahan/desa yang cocok dengan dukungan pagination.",
                "tags": [
                    "Kode Pos"
                ],
                "parameters": [
                    {
                        "name": "search",
                        "in": "query",
                        "description": "Kata kunci kode pos (awalan) atau nama kelurahan (contoh: 101 atau Gambir)",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "pos_code",
                        "in": "query",
                        "description": "Filter kode pos spesifik",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "description": "Jumlah data per halaman (default 20, maks 100)",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "default": 20
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Daftar kode pos berhasil diambil"
                    }
                }
            }
        },
        "/v1/kodepos/{code}": {
            "get": {
                "summary": "Detail Hierarki Wilayah berdasarkan Kode Pos",
                "description": "Mengambil data kelurahan, kecamatan, kabupaten/kota, dan provinsi lengkap secara instan dari 5-digit kode pos.",
                "tags": [
                    "Kode Pos"
                ],
                "parameters": [
                    {
                        "name": "code",
                        "in": "path",
                        "description": "5-digit kode pos resmi Indonesia (contoh: 10110 atau 98547)",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Data hierarki kode pos ditemukan"
                    },
                    "404": {
                        "description": "Kode pos tidak ditemukan"
                    }
                }
            }
        },
        "/v1/cascader/provinsi/{id}": {
            "get": {
                "summary": "Hierarki Cascader Provinsi (Provinsi -> Kab/Kota -> Kecamatan)",
                "description": "Mengambil seluruh pohon hierarki di bawah provinsi dalam satu kali panggilan jaringan tunggal (single network trip) untuk efisiensi dropdown bertingkat di frontend.",
                "tags": [
                    "Cascader Hierarki"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "description": "ID atau 2-digit kode provinsi (contoh: 31 atau 96)",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Pohon cascader provinsi berhasil dimuat"
                    },
                    "404": {
                        "description": "Provinsi tidak ditemukan"
                    }
                }
            }
        },
        "/v1/cascader/kabupaten/{id}": {
            "get": {
                "summary": "Hierarki Cascader Kabupaten (Kab/Kota -> Kecamatan -> Kelurahan)",
                "description": "Mengambil seluruh pohon hierarki di bawah kabupaten/kota dalam satu kali panggilan jaringan tunggal untuk form pemilihan alamat.",
                "tags": [
                    "Cascader Hierarki"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "description": "ID atau 4-digit full_code kabupaten (contoh: 3171 atau 9601)",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Pohon cascader kabupaten berhasil dimuat"
                    },
                    "404": {
                        "description": "Kabupaten tidak ditemukan"
                    }
                }
            }
        }
    }
}