Geolokasi pengunjung untuk situs web Anda

Panggil GET /v1/geo langsung dari browser pengunjung untuk mendapatkan negara, kota, zona waktu, dan konteks regional yang tersedia dari koneksi tersebut. Konfigurasikan allowed origin Anda, tambahkan publishable key Anda, dan tentukan bagaimana aplikasi Anda harus menangani responsnya.

Dapatkan API key visitor gratis Baca panduan cepat →

Request berasal dari browser pengunjung

GET /v1/geo selalu menjelaskan klien mana pun yang terhubung ke sana. Panggil dari browser pengunjung untuk menerima data lokasi koneksi tersebut; request yang dikirim dari server aplikasi Anda menjelaskan koneksi server itu sendiri, bukan koneksi pengunjung. Jika Anda sudah memiliki alamat IP pengguna akhir dan perlu menyelesaikannya di backend Anda, gunakan API pencarian IP yang terpisah. Visitor key bersifat publishable — dirancang untuk muncul di kode browser — jadi kontrol sebenarnya adalah daftar allowed-origins yang dikonfigurasi untuknya, bukan kerahasiaan key itu sendiri.

Rancang sebagai saran, bukan pengalihan paksa

Seorang traveler mungkin menggunakan jaringan di satu negara sambil lebih memilih bahasa lain, dan VPN dapat menempatkan koneksi di tempat yang sama sekali berbeda. Berikan pengunjung cara yang terlihat untuk mengubah bahasa, negara, atau mata uang yang disarankan, dan simpan pilihan itu alih-alih menghitungnya ulang dari lokasi di setiap kunjungan.

Konteks keamanan hanya pada paket yang memenuhi syarat

Pada paket yang menyertakannya, respons dapat membawa indikator VPN/Tor/ancaman berbasis daftar. Objek security yang tidak ada berarti field tersebut tidak termasuk dalam paket Anda, bukan berarti jaringan tersebut diperiksa dan dinyatakan aman; nilai false berarti tidak ada kecocokan dalam data sumber yang tersedia, yang tidak sama dengan jaminan bebas masalah. Cakupan berbeda menurut indikator dan versi IP — deteksi Tor IPv6, misalnya, saat ini belum diimplementasikan.

Konteks berguna dalam respons

country, region, city, latitude, longitude: Perkiraan lokasi untuk request yang terhubung. Bukan posisi perangkat atau GPS, dan bukan bukti keberadaan orang tertentu.
timezone, currency, callingCode: Konteks regional yang diturunkan dari lokasi yang diselesaikan, berguna sebagai saran awal.
asn, asOrganization: Jaringan yang terhubung dan operatornya, jika tersedia. Nama organisasi bukan identitas seseorang.
security: Sepenuhnya tidak ada kecuali paket Anda menyertakannya. Jika ada: isVpn, isTor, isDatacenter, isThreat, isSanctionedNetwork — indikator berbasis daftar, bukan jaminan keamanan.

Tambahkan request pertama

Browser JavaScript

async function loadVisitorLocation() {
  const response = await fetch('https://api.watch-ip.com/v1/geo', {
    headers: { 'X-Api-Key': 'YOUR_PUBLISHABLE_KEY' },
  });

  if (!response.ok) {
    throw new Error(`Visitor geolocation failed (${response.status})`);
  }

  const geo = await response.json();
  return { country: geo.country ?? null, city: geo.city ?? null, timezone: geo.timezone ?? null };
}

Ganti placeholder-nya dengan visitor key Anda dan jalankan halaman dari origin yang diizinkan untuk key tersebut. Jaga agar pengalaman default situs Anda tetap tersedia jika request gagal atau ada field yang hilang.

Pertanyaan yang sering diajukan

Apakah ini meminta izin lokasi perangkat?

Tidak. Request berbasis IP ini tidak menggunakan Geolocation API perangkat milik browser — ia memperkirakan lokasi dari koneksi, bukan meminta koordinat yang disediakan perangkat. Kewajiban privasi dan persetujuan Anda sendiri tetap tergantung pada bagaimana aplikasi Anda menggunakan hasilnya.

Bisakah saya mengirim alamat IP ke /v1/geo?

Tidak. Endpoint ini selalu menjelaskan klien yang terhubung. Gunakan /v1/lookup/{ip} dari backend Anda saat ingin mengirim sebuah alamat.

Kenapa request yang dirender di server menampilkan lokasi penyedia hosting saya?

Server adalah klien yang terhubung untuk request tersebut. Pindahkan request visitor ke kode browser, atau gunakan endpoint pencarian IP dari backend Anda dengan sumber IP pengguna akhir yang tepercaya.

Apakah kota atau koordinatnya presisi?

Tidak. Geolokasi IP adalah perkiraan yang terkait dengan koneksi, bukan posisi presisi seseorang.

Bisakah saya menggunakan secret key di browser?

Tidak. Gunakan publishable visitor key untuk endpoint ini, dan simpan secret key pencarian hanya di lingkungan backend Anda.