Free Forever, No Registration

API Kode Pos Indonesia

REST API gratis untuk akses 83.000+ kode pos Indonesia. Response JSON, CORS enabled, cocok untuk kurir, e-commerce, fintech, atau project hobi Anda.

Quickstart Try It Endpoints

83.000+

Kode pos & kelurahan

38 Provinsi

Coverage 100% Indonesia

No Auth

Tanpa API key required

<200ms

Response time avg

Quickstart

Pilih bahasa Anda. Tidak perlu auth, tinggal hit endpoint langsung.

bash

# Cari kode pos terdekat dari koordinat
curl "https://carikodepos.id/api/postal-codes/nearby?lat=-6.2&lng=106.8&limit=5"

# Lookup nama wilayah
curl "https://carikodepos.id/api/search?q=menteng&limit=5"

# Bulk lookup
curl -X POST "https://carikodepos.id/api/postal-codes/bulk" \
  -H "Content-Type: application/json" \
  -d '{"entries":["10310","12345","DUREN SAWIT"]}'

Try API Live

Hit endpoint langsung dari browser, lihat response JSON real-time.

GET

/api/postal-codes/nearby

Klik Send Request untuk hit endpoint dan lihat hasilnya.

Authentication

Saat ini API tidak butuh authentication. Endpoint publik untuk data kode pos terbuka untuk siapa saja.

Future: kalau ada tier dengan rate limit lebih tinggi, akan pakai header X-API-Key.

Rate Limits

500 req/detik per IP untuk endpoint API
Response headers: X-RateLimit-Limit, X-RateLimit-Remaining
Status 429 + Retry-After kalau exceed

Endpoints Reference

Base URL: https://carikodepos.id

Kode Pos

GET
`/api/postal-codes`

List & Search Kode Pos

Ambil daftar kode pos dengan filter dan pagination. Mendukung filter by nama, provinsi/kota/kecamatan/desa ID, dan pencarian by koordinat GPS.

Parameters

Nama	Tipe	Required	Default	Deskripsi
search	string	opsional	-	Cari di code, nama district/city/province/village
page	number	opsional	1	Nomor halaman
limit	number	opsional	20	Jumlah per halaman (max 100)
provinceId	string	opsional	-	Filter berdasarkan ID provinsi
cityId	string	opsional	-	Filter berdasarkan ID kota
districtId	string	opsional	-	Filter berdasarkan ID kecamatan
villageId	string	opsional	-	Filter berdasarkan ID desa
latitude	number	opsional	-	Geo search: latitude (decimal)
longitude	number	opsional	-	Geo search: longitude (decimal)
radius	number	opsional	10	Radius geo search dalam km (max 50)

Contoh Request & Response

bash

GET https://carikodepos.id/api/postal-codes?search=menteng&limit=3

json

{
  "success": true,
  "data": {
    "postalCodes": [
      {
        "id": "...",
        "code": "10310",
        "village": { "name": "Menteng", "slug": "menteng" },
        "district": { "name": "Menteng", "slug": "menteng" },
        "city": { "name": "Kota Jakarta Pusat", "slug": "kota-jakarta-pusat" },
        "province": { "name": "DKI Jakarta", "slug": "dki-jakarta" }
      }
    ],
    "pagination": { "page": 1, "limit": 3, "total": 3, "totalPages": 1 }
  }
}

GET
`/api/postal-codes/nearby`

Cari Kode Pos Terdekat (Geo)

Cari kode pos terdekat dari koordinat lat/lng tertentu. Hasil disortir by jarak (km) dan dilengkapi info village/district/city.

Parameters

Nama	Tipe	Required	Default	Deskripsi
lat	number	Required	-	Latitude (-90 sampai 90)
lng	number	Required	-	Longitude (-180 sampai 180)
limit	number	opsional	10	Maks hasil (max 20)
radius	number	opsional	15	Radius km (max 50)
excludeVillageId	string	opsional	-	Skip village ID tertentu

Contoh Request & Response

bash

GET https://carikodepos.id/api/postal-codes/nearby?lat=-6.2&lng=106.8&limit=3

json

{
  "success": true,
  "data": [
    {
      "villageName": "Menteng",
      "postalCode": "10310",
      "districtName": "Menteng",
      "cityName": "Kota Jakarta Pusat",
      "distanceKm": 0.42
    }
  ]
}

GET
`/api/postal-codes/trending`

Trending / Popular Postal Codes

Top kode pos paling sering dicari user. Cache 30 menit, berdasarkan analisis search query real.

Parameters

Nama	Tipe	Required	Default	Deskripsi
period	string	opsional	week	day \| week \| month \| all
limit	number	opsional	20	Maks hasil (max 50)

Contoh Request & Response

bash

GET https://carikodepos.id/api/postal-codes/trending?period=week&limit=2

json

{
  "success": true,
  "data": {
    "items": [
      {
        "type": "postal",
        "query": "14340",
        "count": 426,
        "code": "14340",
        "label": "Kode Pos 14340",
        "href": "/kode-pos/14340"
      }
    ],
    "period": "week",
    "total": 2
  }
}

POST
`/api/postal-codes/bulk`

Bulk Lookup

Lookup banyak kode pos atau nama wilayah sekaligus dalam 1 request (max 1.000 entries). Mode auto: 5-digit numeric → cari by code, text → cari by nama.

Parameters

Nama	Tipe	Required	Default	Deskripsi
entries	string[]	Required	-	Array string (kode pos atau nama)
mode	string	opsional	auto	auto \| code \| name

Contoh Request & Response

bash

GET https://carikodepos.idPOST /api/postal-codes/bulk

json

{
  "success": true,
  "data": {
    "results": [
      { "index": 0, "input": "10310", "status": "matched",
        "postalCode": "10310", "villageName": "Menteng" }
    ],
    "summary": { "total": 1, "matched": 1, "multiple": 0, "notFound": 0, "invalid": 0 }
  }
}

Search & Wilayah

GET
`/api/search`

Global Search

Cari kode pos, kelurahan, kecamatan, kota, atau provinsi dalam satu endpoint.

Parameters

Nama	Tipe	Required	Default	Deskripsi
q	string	Required	-	Query pencarian (min 2 karakter)
type	string	opsional	-	Filter: postal-code \| village \| district \| city \| province \| article
limit	number	opsional	10	Maks hasil per kategori
page	number	opsional	1	Halaman

Contoh Request & Response

bash

GET https://carikodepos.id/api/search?q=jakarta&limit=2

json

{
  "success": true,
  "data": [
    { "type": "city", "name": "Kota Jakarta Pusat", "slug": "kota-jakarta-pusat" },
    { "type": "city", "name": "Kota Jakarta Selatan", "slug": "kota-jakarta-selatan" }
  ]
}

GET
`/api/search/autocomplete`

Autocomplete Suggestions

Suggestion ringan untuk dropdown search box. Limit ketat, cache-friendly.

Parameters

Nama	Tipe	Required	Default	Deskripsi
q	string	Required	-	Query (min 2 char text, 3 char numeric)
limit	number	opsional	8	Max 10

Contoh Request & Response

bash

GET https://carikodepos.id/api/search/autocomplete?q=mente&limit=3

json

{
  "success": true,
  "data": [
    { "type": "village", "label": "Menteng", "sublabel": "Kelurahan/Desa · Menteng, Jakarta Pusat", "href": "/desa/menteng" }
  ]
}

GET
`/api/provinces`

List Semua Provinsi

Daftar 38 provinsi Indonesia dengan slug dan kode.

Contoh Request & Response

bash

GET https://carikodepos.id/api/provinces

json

{
  "success": true,
  "data": [
    { "id": "...", "code": "31", "name": "DKI Jakarta", "slug": "dki-jakarta" }
  ]
}

GET
`/api/cities`

List Kota/Kabupaten

Daftar kota/kabupaten dengan filter by provinsi.

Parameters

Nama	Tipe	Required	Default	Deskripsi
provinceId	string	opsional	-	Filter by provinsi
search	string	opsional	-	Cari nama kota

Contoh Request & Response

bash

GET https://carikodepos.id/api/cities?provinceId=...&limit=2

json

{ "success": true, "data": [...] }

GET
`/api/districts`

List Kecamatan

Daftar kecamatan dengan filter by kota.

Parameters

Nama	Tipe	Required	Default	Deskripsi
cityId	string	opsional	-	Filter by kota

Contoh Request & Response

bash

GET https://carikodepos.id/api/districts?cityId=...

json

{ "success": true, "data": [...] }

GET
`/api/villages`

List Kelurahan/Desa

Daftar kelurahan/desa dengan filter by kecamatan.

Parameters

Nama	Tipe	Required	Default	Deskripsi
districtId	string	opsional	-	Filter by kecamatan

Contoh Request & Response

bash

GET https://carikodepos.id/api/villages?districtId=...

json

{ "success": true, "data": [...] }

Artikel

GET
`/api/articles/[slug]`

Detail Artikel

Ambil detail artikel berdasarkan slug.

Parameters

Nama	Tipe	Required	Default	Deskripsi
slug	string	Required	-	Slug artikel

Contoh Request & Response

bash

GET https://carikodepos.id/api/articles/cara-cek-kode-pos

json

{
  "id": "...",
  "title": "Cara Cek Kode Pos",
  "content": "...",
  "author": { "name": "Admin" }
}

Error Format

Semua error response mengikuti shape konsisten:

json

{
  "success": false,
  "error": "Pesan error human-readable"
}

200

400

Bad Request

404

Not Found

413

Too Large

429

Rate Limit

500

Server Error

CORS

CORS enabled untuk semua origin (*). Anda bisa pakai dari frontend browser tanpa proxy.

Caching

Endpoint dengan data stable (autocomplete, nearby, trending) cache di edge sampai ke 30 menit. Hint via header Cache-Control.

Punya pertanyaan atau request?

Email kami atau buka issue. Kami senang dengar feedback developer.

Hubungi Kami Coba Bulk Lookup

Quickstart

Try API Live

Authentication

Rate Limits

Endpoints Reference

Kode Pos

GET/api/postal-codes

Parameters

Contoh Request & Response

GET/api/postal-codes/nearby

Parameters

Contoh Request & Response

GET/api/postal-codes/trending

Parameters

Contoh Request & Response

POST/api/postal-codes/bulk

Parameters

Contoh Request & Response

Search & Wilayah

GET/api/search

Parameters

Contoh Request & Response

GET/api/search/autocomplete

Parameters

Contoh Request & Response

GET/api/provinces

Contoh Request & Response

GET/api/cities

Parameters

Contoh Request & Response

GET/api/districts

Parameters

Contoh Request & Response

GET/api/villages

Parameters

Contoh Request & Response

Artikel

GET/api/articles/[slug]

Parameters

Contoh Request & Response

Error Format

CORS

Caching

Punya pertanyaan atau request?

GET
`/api/postal-codes`

GET
`/api/postal-codes/nearby`

GET
`/api/postal-codes/trending`

POST
`/api/postal-codes/bulk`

GET
`/api/search`

GET
`/api/search/autocomplete`

GET
`/api/provinces`

GET
`/api/cities`

GET
`/api/districts`

GET
`/api/villages`

GET
`/api/articles/[slug]`