API Geocoding Indonesia: Cara Ubah Alamat Jadi Koordinat dan Cari Cabang Terdekat (curl, Node.js, Python)

Oleh , 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.

Sampul APIPedia: judul "Alamat jadi koordinat, lalu cari cabang terdekat" dengan chip GET /v1/maps/geocode dan GET /v1/maps/reverse, serta kartu terminal: hasil geocode Alun-Alun Kota Malang (lat -7.9826131, lon 112.63082) dan jarak ke tiga cabang, terdekat 0,70 km.

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.

ItemDetail
Alamat ke koordinatGET https://api.apipedia.id/v1/maps/geocode?q=...
Koordinat ke alamatGET https://api.apipedia.id/v1/maps/reverse?lat=...&lon=...
Parameter geocodeq: nama tempat atau alamat, minimal 3 karakter
Parameter reverselat (-90 sampai 90) dan lon (-180 sampai 180)
AutentikasiHeader Authorization: Bearer apk_xxx
Hasil geocodejumlah dan larik hasil berisi lat, lon, display_name, type, address
Cache24 jam di sisi gateway; field cached menandai hasil dari cache
Sumber dataOpenStreetMap Nominatim, data © OpenStreetMap contributors (ODbL)
Belum tersediaEndpoint jarak dan polyline
TierFree 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.

Diagram alur empat langkah fitur cabang terdekat: pembeli mengetik alamat minimal 3 karakter (contoh q=Alun-Alun Kota Malang), backend memanggil GET /v1/maps/geocode dan menerima daftar kandidat berisi lat, lon, dan alamat terurai, sistem memilih satu kandidat dengan menyaring address.state atau meminta pembeli memilih, lalu menghitung jarak ke tiap cabang dengan rumus haversine dan mengurutkannya; hasil contoh Kiduldalem 0,70 km. Catatan: jarak dihitung di kode Anda karena endpoint jarak dan polyline belum tersedia, dan haversine memberi jarak garis lurus, bukan jarak tempuh di jalan.

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
  }
}
FieldArti
jumlahBanyaknya kandidat yang ditemukan. Pada uji ini ada 5.
hasil[].lat, hasil[].lonKoordinat dalam derajat desimal, bertipe angka.
hasil[].display_nameAlamat lengkap dalam satu baris, cocok untuk ditampilkan ke pengguna.
hasil[].typeJenis objek di peta, misalnya park, hotel, atau mall.
hasil[].addressAlamat terurai: road, village, suburb, city_district, city, county, state, postcode, country.
cachedtrue 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:

CabangJarak garis lurus
Cabang Kiduldalem0,70 km
Cabang Sumbersari2,49 km
Cabang Surabaya81,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.

Perbandingan dua endpoint Maps Encoder dengan data uji nyata. Geocode, GET /v1/maps/geocode: masukan q Alun-Alun Kota Malang menghasilkan 5 kandidat, kandidat pertama di lat -7.9826131 dan lon 112.63082, type park, address.state Jawa Timur, address.postcode null karena tidak selalu terisi. Reverse, GET /v1/maps/reverse: masukan lat -7.2575 dan lon 112.7521 menghasilkan address.road Jalan Kanginan I, village Ketabang, city Surabaya, state Jawa Timur, postcode 60272. Catatan: cache 24 jam, ada field cached, tanpa jarak rute, tanpa polyline, dan kelengkapan data OpenStreetMap berbeda antar daerah.

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 postcode bernilai null, 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 dengan address.state atau tampilkan pilihan.
  • Tidak menangani hasil kosong. Periksa jumlah atau panjang hasil sebelum membaca isinya.
  • Tidak meng-encode alamat. Spasi, koma, dan titik harus dikodekan. Pakai encodeURIComponent atau --data-urlencode.
  • Mengirim kata kunci terlalu pendek. Parameter q minimal 3 karakter. Tambahkan nama kota agar hasilnya lebih tepat.
  • Menukar lat dan lon. Untuk Indonesia, lat berkisar -11 sampai 6 dan lon 95 sampai 141.
  • Memanggil dari browser. Kunci apk_xxx akan terbaca siapa pun. Panggil dari backend.
  • Menyebut jarak haversine sebagai jarak tempuh. Beri label "jarak garis lurus" di antarmuka.

Kode status yang perlu ditangani

StatusArtiTindakan
200Permintaan berhasilPeriksa jumlah, lalu baca hasil
400Parameter tidak valid, misalnya q kurang dari 3 karakterBaca message dan perbaiki masukan
401Token tidak ada, tidak dikenal, atau kedaluwarsaPeriksa header Authorization
429Batas request terlampauiTunggu, 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:

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.