GraphQL API

GraphQL API memberikan query fleksibel — ambil hanya data yang Anda butuhkan. Satu endpoint untuk semua data kode pos Indonesia.

Endpoint & Headers

Kirim request POST ke endpoint GraphQL dengan header Authorization: Bearer untuk autentikasi.

Endpoint: https://api.kodepos.dev/kodepos/graphql
Method: POST
Header: Authorization: Bearer kp_live_xxxxxxxxxxxxxxxx
Content-Type: application/json

Contoh request menggunakan cURL:

curl -X POST "https://api.kodepos.dev/kodepos/graphql" \
  -H "Authorization: Bearer kp_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ provinces(first: 5) { items { code name } pagination { hasNextPage endCursor } } }"}'

Daftar Query

Berikut adalah seluruh query yang tersedia di GraphQL API:

Schema Types

Berikut adalah tipe data utama yang tersedia di GraphQL API:

Contoh Query

Daftar Provinsi dengan Pagination

Ambil daftar provinsi dengan pagination:

query {
  provinces(first: 5) {
    items {
      code
      name
    }
    pagination {
      hasNextPage
      endCursor
    }
  }
}

Response:

{
  "data": {
    "provinces": {
      "items": [
        { "code": "11", "name": "Aceh" },
        { "code": "12", "name": "Sumatera Utara" },
        { "code": "13", "name": "Sumatera Barat" },
        { "code": "14", "name": "Riau" },
        { "code": "15", "name": "Jambi" }
      ],
      "pagination": {
        "hasNextPage": true,
        "endCursor": "eyJjb2RlIjoiMTUifQ=="
      }
    }
  }
}

Daftar Kota dalam Provinsi

Ambil daftar kota/kabupaten — parameter provinceCode wajib diisi:

query {
  cities(provinceCode: "11", first: 5) {
    items {
      code
      name
    }
    pagination {
      hasNextPage
      endCursor
    }
  }
}

Response:

{
  "data": {
    "cities": {
      "items": [
        { "code": "11.01", "name": "Kab. Aceh Selatan" },
        { "code": "11.02", "name": "Kab. Aceh Tenggara" },
        { "code": "11.03", "name": "Kab. Aceh Timur" },
        { "code": "11.04", "name": "Kab. Aceh Tengah" },
        { "code": "11.05", "name": "Kab. Aceh Barat" }
      ],
      "pagination": {
        "hasNextPage": true,
        "endCursor": "eyJjb2RlIjoiMTEuMDUifQ=="
      }
    }
  }
}

Detail Kota dengan Provinsi

Ambil detail kota beserta data provinsi induk — hanya field yang Anda butuhkan:

query {
  city(code: "11.01") {
    code
    name
    province {
      code
      name
    }
  }
}

Response:

{
  "data": {
    "city": {
      "code": "11.01",
      "name": "Kab. Aceh Selatan",
      "province": {
        "code": "11",
        "name": "Aceh"
      }
    }
  }
}

Daftar Kecamatan dalam Kota

Ambil daftar kecamatan — parameter cityCode wajib diisi:

query {
  districts(cityCode: "11.01", first: 5) {
    items {
      code
      name
    }
    pagination {
      hasNextPage
      endCursor
    }
  }
}

Response:

{
  "data": {
    "districts": {
      "items": [
        { "code": "11.01.01", "name": "Bakongan" },
        { "code": "11.01.02", "name": "Kluet Utara" },
        { "code": "11.01.03", "name": "Kluet Selatan" },
        { "code": "11.01.04", "name": "Kluet Timur" },
        { "code": "11.01.05", "name": "Kluet Tengah" }
      ],
      "pagination": {
        "hasNextPage": true,
        "endCursor": "eyJjb2RlIjoiMTEuMDEuMDUifQ=="
      }
    }
  }
}

Kecamatan dengan Hierarki Lengkap

Ambil detail kecamatan beserta seluruh hierarki wilayah:

query {
  district(code: "11.01.01") {
    code
    name
    city {
      code
      name
      province {
        code
        name
      }
    }
  }
}

Response:

{
  "data": {
    "district": {
      "code": "11.01.01",
      "name": "Bakongan",
      "city": {
        "code": "11.01",
        "name": "Kab. Aceh Selatan",
        "province": {
          "code": "11",
          "name": "Aceh"
        }
      }
    }
  }
}

Daftar Kelurahan/Desa dalam Kecamatan

Ambil daftar kelurahan/desa — parameter districtCode wajib diisi:

query {
  subdistricts(districtCode: "11.01.01", first: 5) {
    items {
      code
      name
      postalCode
    }
    pagination {
      hasNextPage
      endCursor
    }
  }
}

Response:

{
  "data": {
    "subdistricts": {
      "items": [
        {
          "code": "11.01.01.2001",
          "name": "Kampung Baru",
          "postalCode": "23761"
        }
      ],
      "pagination": {
        "hasNextPage": false,
        "endCursor": null
      }
    }
  }
}

Pencarian Kelurahan/Desa

Cari kelurahan/desa berdasarkan kata kunci dengan hierarki lengkap:

query {
  search(q: "menteng", first: 5) {
    items {
      code
      name
      postalCode
      district {
        code
        name
      }
      city {
        code
        name
      }
      province {
        code
        name
      }
    }
    pagination {
      hasNextPage
      endCursor
    }
  }
}

Response:

{
  "data": {
    "search": {
      "items": [
        {
          "code": "31.73.06.1003",
          "name": "Menteng",
          "postalCode": "10310",
          "district": { "code": "31.73.06", "name": "Menteng" },
          "city": { "code": "31.73", "name": "Kota Jakarta Pusat" },
          "province": { "code": "31", "name": "DKI Jakarta" }
        }
      ],
      "pagination": {
        "hasNextPage": false,
        "endCursor": null
      }
    }
  }
}