API Geocoding Indonesia: Cara Ubah Alamat Jadi Koordinat dan Cari Cabang Terdekat (curl, Node.js, Python)
Oleh Tim APIPedia, Tim Engineering APIPedia · Terbit · Diperbarui · 10 menit baca
API geocoding APIPedia mengubah alamat jadi koordinat lewat GET /v1/maps/geocode. Tutorial cabang terdekat dengan contoh curl, Node.js, dan Python.

API geocoding APIPedia (produk Maps Encoder) mengubah nama tempat atau alamat menjadi koordinat lewat GET /v1/maps/geocode, dan mengubah koordinat menjadi alamat lewat GET /v1/maps/reverse. Hasilnya berisi lat, lon, display_name, dan alamat yang sudah diurai per bagian.
Tutorial ini memakai kasus yang sering muncul di toko online dan aplikasi layanan: pembeli mengetik alamat, lalu sistem menunjukkan cabang terdekat. Anda akan melihat contoh curl, Node.js, dan Python, respons nyata dari uji kami pada 16 November 2026, serta batas yang perlu Anda tahu sebelum memasangnya.
Ringkasan cepat: apa yang perlu Anda tahu?
Maps Encoder punya dua endpoint GET: satu untuk alamat ke koordinat, satu untuk koordinat ke alamat. Tabel berikut merangkum intinya.
| Item | Detail |
|---|---|
| Alamat ke koordinat | GET https://api.apipedia.id/v1/maps/geocode?q=... |
| Koordinat ke alamat | GET https://api.apipedia.id/v1/maps/reverse?lat=...&lon=... |
| Parameter geocode | q: nama tempat atau alamat, minimal 3 karakter |
| Parameter reverse | lat (-90 sampai 90) dan lon (-180 sampai 180) |
| Autentikasi | Header Authorization: Bearer apk_xxx |
| Hasil geocode | jumlah dan larik hasil berisi lat, lon, display_name, type, address |
| Cache | 24 jam di sisi gateway; field cached menandai hasil dari cache |
| Sumber data | OpenStreetMap Nominatim, data © OpenStreetMap contributors (ODbL) |
| Belum tersedia | Endpoint jarak dan polyline |
| Tier | Free pada katalog, versi Maps Encoder 1.1.4 |
Masalah apa yang diselesaikan API geocoding?
API geocoding menjembatani teks alamat yang diketik manusia dengan angka koordinat yang bisa dihitung mesin. Tanpa koordinat, sistem Anda tidak bisa menjawab pertanyaan sederhana seperti "cabang mana yang paling dekat dengan pembeli ini?".
Tiga kebutuhan paling umum:
- Cabang atau gudang terdekat. Pembeli mengetik alamat, sistem memilih titik layanan terdekat.
- Isi alamat dari lokasi perangkat. Aplikasi mendapat koordinat GPS, lalu reverse geocode mengisi nama jalan, kota, dan kode pos di form.
- Titik di peta. Daftar alamat pelanggan atau mitra diubah menjadi pin untuk dashboard internal.

Apa yang perlu disiapkan sebelum mulai?
Anda hanya butuh satu kunci API APIPedia. Daftar atau masuk di console.apipedia.id, buka menu Token API, lalu buat kunci baru. Kunci berawalan apk_ dan dikirim lewat header Authorization: Bearer apk_xxx.
Simpan kunci di variabel lingkungan server, misalnya APIPEDIA_KEY, dan panggil API dari backend, bukan dari browser. Siapkan juga daftar cabang Anda beserta koordinatnya. Contoh di artikel ini memakai tiga cabang fiktif.
Langkah 1: bagaimana mengubah alamat menjadi koordinat dengan curl?
Kirim nama tempat atau alamat sebagai parameter q ke GET /v1/maps/geocode. Opsi --data-urlencode membuat spasi dan tanda baca di alamat dikodekan dengan benar.
curl -s -G https://api.apipedia.id/v1/maps/geocode \
-H "Authorization: Bearer apk_xxx" \
--data-urlencode "q=Alun-Alun Kota Malang"
Respons nyata dari uji kami, dengan tiga kandidat terakhir dipersingkat:
{
"is_success": true,
"message": "Geocoding results retrieved. Data © OpenStreetMap contributors (ODbL).",
"data": {
"q": "Alun-Alun Kota Malang",
"jumlah": 5,
"hasil": [
{
"lat": -7.9826131,
"lon": 112.63082,
"display_name": "Alun-Alun Merdeka, Kiduldalem, Kota Malang, Klojen, Jawa Timur, Indonesia",
"type": "park",
"address": {
"road": null,
"village": null,
"suburb": "Kiduldalem",
"city_district": null,
"city": "Kota Malang",
"county": null,
"state": "Jawa Timur",
"postcode": null,
"country": "Indonesia"
}
},
{
"lat": -7.977166,
"lon": 112.6340385,
"display_name": "Alun-Alun Bundar Malang, RW. 08, KEL. KIDUL DALEM, KOTA MALANG, Kiduldalem, Klojen, Jawa Timur, Indonesia",
"type": "park"
}
],
"cached": false
}
}
| Field | Arti |
|---|---|
jumlah | Banyaknya kandidat yang ditemukan. Pada uji ini ada 5. |
hasil[].lat, hasil[].lon | Koordinat dalam derajat desimal, bertipe angka. |
hasil[].display_name | Alamat lengkap dalam satu baris, cocok untuk ditampilkan ke pengguna. |
hasil[].type | Jenis objek di peta, misalnya park, hotel, atau mall. |
hasil[].address | Alamat terurai: road, village, suburb, city_district, city, county, state, postcode, country. |
cached | true bila jawaban diambil dari cache gateway. |
Dua hal terlihat dari respons ini. Pertama, satu kata kunci bisa menghasilkan beberapa kandidat: selain dua alun-alun, hasil uji juga memuat sebuah hotel dan sebuah mal yang namanya mirip. Kedua, bagian address yang tidak diketahui bernilai null, termasuk postcode pada kandidat pertama.
Langkah 2: bagaimana mencari cabang terdekat di Node.js?
Ambil koordinat alamat pembeli dari geocode, lalu hitung jarak ke setiap cabang dengan rumus haversine di kode Anda sendiri. Maps Encoder belum punya endpoint jarak, jadi perhitungan ini memang dikerjakan di sisi aplikasi. Contoh berikut berjalan di Node.js 18 ke atas tanpa dependensi tambahan.
const BASE = "https://api.apipedia.id/v1";
const headers = { Authorization: `Bearer ${process.env.APIPEDIA_KEY}` }; // apk_xxx
// Daftar cabang fiktif. Simpan koordinat cabang Anda di database.
const CABANG = [
{ nama: "Cabang Sumbersari", lat: -7.9633709, lon: 112.6192541 },
{ nama: "Cabang Kiduldalem", lat: -7.977166, lon: 112.6340385 },
{ nama: "Cabang Surabaya", lat: -7.2573672, lon: 112.7520999 },
];
async function geocode(alamat) {
const url = `${BASE}/maps/geocode?q=${encodeURIComponent(alamat)}`;
const res = await fetch(url, { headers });
const body = await res.json();
if (!body.is_success) throw new Error(`HTTP ${res.status}: ${body.message}`);
return body.data.hasil; // bisa kosong
}
// Jarak garis lurus (haversine), dalam kilometer.
function jarakKm(a, b) {
const rad = (x) => (x * Math.PI) / 180;
const dLat = rad(b.lat - a.lat);
const dLon = rad(b.lon - a.lon);
const h =
Math.sin(dLat / 2) ** 2 +
Math.cos(rad(a.lat)) * Math.cos(rad(b.lat)) * Math.sin(dLon / 2) ** 2;
return 2 * 6371 * Math.asin(Math.sqrt(h));
}
export async function cabangTerdekat(alamat, provinsi) {
const hasil = await geocode(alamat);
const kandidat = provinsi
? hasil.filter((h) => h.address.state === provinsi)
: hasil;
if (kandidat.length === 0) return { ok: false, alasan: "Alamat tidak ditemukan." };
const titik = kandidat[0];
const urut = CABANG
.map((c) => ({ ...c, km: Number(jarakKm(titik, c).toFixed(2)) }))
.sort((x, y) => x.km - y.km);
return { ok: true, alamat: titik.display_name, terdekat: urut[0], semua: urut };
}
console.log(await cabangTerdekat("Alun-Alun Kota Malang", "Jawa Timur"));
Dengan koordinat dari respons di Langkah 1, fungsi ini menghasilkan urutan berikut:
| Cabang | Jarak garis lurus |
|---|---|
| Cabang Kiduldalem | 0,70 km |
| Cabang Sumbersari | 2,49 km |
| Cabang Surabaya | 81,74 km |
Parameter provinsi berguna untuk menyaring kandidat yang salah daerah. Banyak nama tempat di Indonesia dipakai di lebih dari satu kota, sehingga menyaring lewat address.state mengurangi salah pilih. Bila kandidatnya masih lebih dari satu, tampilkan display_name sebagai pilihan dan biarkan pembeli memilih.
Langkah 3: bagaimana mengubah koordinat menjadi alamat?
Kirim lat dan lon ke GET /v1/maps/reverse, dan API mengembalikan satu alamat terdekat dari titik itu. Pola ini dipakai saat aplikasi sudah memegang koordinat dari GPS perangkat dan ingin mengisi form alamat.
curl -s -G https://api.apipedia.id/v1/maps/reverse \
-H "Authorization: Bearer apk_xxx" \
-d lat=-7.2575 -d lon=112.7521
Respons nyata dari uji kami:
{
"is_success": true,
"message": "Address retrieved from coordinates. Data © OpenStreetMap contributors (ODbL).",
"data": {
"lat": -7.2573672,
"lon": 112.7520999,
"display_name": "Jalan Kanginan I, RW 01, Ketabang, Genteng, Surabaya, Jawa Timur, 60272, Indonesia",
"type": "living_street",
"address": {
"road": "Jalan Kanginan I",
"village": "Ketabang",
"suburb": null,
"city_district": null,
"city": "Surabaya",
"county": null,
"state": "Jawa Timur",
"postcode": "60272",
"country": "Indonesia"
},
"cached": false
}
}
Perhatikan bahwa lat dan lon di respons sedikit berbeda dari yang dikirim. Itu koordinat objek peta terdekat (di sini sebuah ruas jalan), bukan titik persis yang Anda minta.

Langkah 4: bagaimana contoh reverse geocode di Python?
Di Python, kirim lat dan lon dengan requests, lalu petakan bagian address ke kolom form Anda. Karena sebagian field bisa null, siapkan cadangan untuk tiap kolom.
import os
from math import asin, cos, radians, sin, sqrt
import requests # pip install requests
BASE = "https://api.apipedia.id/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['APIPEDIA_KEY']}"} # apk_xxx
def alamat_dari_koordinat(lat, lon):
res = requests.get(
f"{BASE}/maps/reverse",
headers=HEADERS,
params={"lat": lat, "lon": lon},
timeout=15,
)
body = res.json()
if not body.get("is_success"):
raise RuntimeError(f"HTTP {res.status_code}: {body.get('message')}")
a = body["data"]["address"]
return {
"lengkap": body["data"]["display_name"],
"jalan": a.get("road"),
"kelurahan": a.get("village") or a.get("suburb"),
"kota": a.get("city") or a.get("county"),
"provinsi": a.get("state"),
"kode_pos": a.get("postcode"),
}
def jarak_km(lat1, lon1, lat2, lon2):
d_lat, d_lon = radians(lat2 - lat1), radians(lon2 - lon1)
h = sin(d_lat / 2) ** 2 + cos(radians(lat1)) * cos(radians(lat2)) * sin(d_lon / 2) ** 2
return 2 * 6371 * asin(sqrt(h))
if __name__ == "__main__":
print(alamat_dari_koordinat(-7.2575, 112.7521))
print(round(jarak_km(-7.9826131, 112.63082, -7.977166, 112.6340385), 2), "km") # 0.7 km
Pada respons Surabaya di atas, nama kelurahan ada di village, sedangkan pada respons Malang di Langkah 1 ada di suburb. Itulah alasan kode memeriksa keduanya.
Apa batas Maps Encoder yang perlu Anda tahu?
Maps Encoder hanya melakukan geocoding dan reverse geocoding; ia tidak menghitung jarak tempuh, rute, atau polyline. Menurut katalog APIPedia, endpoint jarak dan polyline belum diimplementasikan.
- Haversine bukan jarak di jalan. Angka 0,70 km di atas adalah garis lurus. Jarak tempuh sebenarnya hampir selalu lebih panjang, jadi jangan pakai angka ini untuk tarif per kilometer.
- Kelengkapan data mengikuti OpenStreetMap. Pusat kota biasanya terpetakan rapi, sedangkan gang kecil atau perumahan baru bisa belum ada.
- Kode pos tidak selalu terisi. Bila
postcodebernilainull, lengkapi lewat API wilayah dan kode pos. - Ada pembatasan laju. Gateway membatasi request mengikuti kebijakan Nominatim, jadi produk ini tidak dirancang untuk geocoding massal ribuan alamat sekaligus.
- Wajib mencantumkan atribusi. Bila hasilnya ditampilkan ke publik, tulis "© OpenStreetMap contributors" sesuai lisensi ODbL.
Kesalahan umum apa yang perlu dihindari?
Kesalahan paling sering adalah memanggil geocode setiap kali halaman dibuka, padahal alamat yang sama menghasilkan koordinat yang sama. Simpan lat dan lon di database saat alamat pertama kali disimpan. Periksa juga hal-hal berikut.
- Langsung memakai
hasil[0]. Kandidat pertama belum tentu yang dimaksud pembeli. Saring denganaddress.stateatau tampilkan pilihan. - Tidak menangani hasil kosong. Periksa
jumlahatau panjanghasilsebelum membaca isinya. - Tidak meng-encode alamat. Spasi, koma, dan titik harus dikodekan. Pakai
encodeURIComponentatau--data-urlencode. - Mengirim kata kunci terlalu pendek. Parameter
qminimal 3 karakter. Tambahkan nama kota agar hasilnya lebih tepat. - Menukar
latdanlon. Untuk Indonesia,latberkisar -11 sampai 6 danlon95 sampai 141. - Memanggil dari browser. Kunci
apk_xxxakan terbaca siapa pun. Panggil dari backend. - Menyebut jarak haversine sebagai jarak tempuh. Beri label "jarak garis lurus" di antarmuka.
Kode status yang perlu ditangani
| Status | Arti | Tindakan |
|---|---|---|
| 200 | Permintaan berhasil | Periksa jumlah, lalu baca hasil |
| 400 | Parameter tidak valid, misalnya q kurang dari 3 karakter | Baca message dan perbaiki masukan |
| 401 | Token tidak ada, tidak dikenal, atau kedaluwarsa | Periksa header Authorization |
| 429 | Batas request terlampaui | Tunggu, lalu ulangi dengan jeda |
Penjelasan lengkap soal 429 ada di artikel rate limit dan error 429.
Pertanyaan yang sering diajukan
Apakah API geocoding APIPedia gratis?
Produk Maps Encoder tercatat di tier Free pada katalog APIPedia. Setiap panggilan tetap dihitung ke kuota request akun Anda.
Dari mana sumber data petanya?
Dari OpenStreetMap lewat Nominatim. Seluruh data peta bersumber dari OpenStreetMap contributors dengan lisensi ODbL, sehingga atribusi perlu dicantumkan saat hasilnya ditampilkan.
Apakah bisa menghitung jarak atau rute antar dua titik?
Belum. Endpoint jarak dan polyline belum tersedia di Maps Encoder. Untuk jarak garis lurus, pakai rumus haversine seperti contoh di atas.
Kenapa satu alamat menghasilkan beberapa kandidat?
Karena pencarian mencocokkan nama, dan banyak tempat punya nama serupa. Pada uji kami, "Alun-Alun Kota Malang" menghasilkan 5 kandidat, termasuk dua alun-alun yang berbeda.
Apakah hasil geocode boleh disimpan di database?
Boleh, dan itu cara yang dianjurkan agar tidak memanggil API berulang untuk alamat yang sama. Gateway sendiri menyimpan cache selama 24 jam.
Bisakah asisten AI memakai API ini?
Bisa. Server MCP APIPedia menyediakan tool maps_geocode dan maps_reverse yang memanggil endpoint yang sama. Cara menyambungkannya ada di panduan menghubungkan APIPedia ke Claude lewat MCP.
Langkah berikutnya: coba di konsol
Fitur cabang terdekat cukup butuh satu request geocode dan satu fungsi haversine di backend. Buat kunci di console.apipedia.id, jalankan contoh curl di atas dengan alamat toko Anda sendiri, lalu pasang fungsi cabangTerdekat di halaman checkout atau halaman lokasi.
Untuk melengkapi alurnya, baca API wilayah dan kode pos untuk dropdown alamat dan API cek ongkir untuk estimasi biaya kirim.
Topik: #api geocoding #maps encoder #reverse geocoding #tutorial #nodejs #python
Tentang penulis
Tim APIPedia — Tim Engineering APIPedia
Tim engineering di balik APIPedia yang membangun dan memelihara API data Indonesia - ongkir, OCR KTP, data wilayah, BMKG, hingga server MCP - dan menulis panduan integrasinya dari pengalaman langsung.