Anda sudah siap!

Untuk mulai mengembangkan, masuklah ke dokumentasi developer kami.

Aktifkan Google Maps Geolocation API

Untuk membantu Anda memulai, kami akan memandu Anda melalui Google Developers Console untuk melakukan beberapa hal terlebih dahulu:

  1. Buat atau pilih sebuah proyek
  2. Aktifkan Google Maps Geolocation API
  3. Buat kunci yang sesuai
Lanjutkan

Google Maps Geolocation API

Ringkasan

Google Maps Geolocation API mengembalikan radius akurasi dan lokasi berdasarkan informasi tentang menara BTS dan simpul WiFi yang bisa dideteksi oleh ponsel klien. Dokumen ini menjelaskan protokol yang digunakan untuk mengirimkan data ini ke server dan mengembalikan respons kepada klien.

Komunikasi dilakukan melalui HTTPS menggunakan POST. Permintaan dan respons diformat sebagai JSON, dan tipe materi dari keduanya adalah application/json.

Sebelum Anda memulai development dengan Geolocation API, periksa persyaratan autentikasi (Anda memerlukan kunci API) dan batas penggunaan API.

Permintaan Geolocation

Permintaan geolokasi dikirim menggunakan POST ke URL berikut:

https://www.googleapis.com/geolocation/v1/geolocate?key=YOUR_API_KEY

Anda harus menetapkan kunci dalam permintaan, yang disertakan sebagai nilai parameter key. key adalah kunci API aplikasi Anda. Kunci ini mengidentifikasi aplikasi Anda untuk keperluan manajemen kuota. Pelajari cara mendapatkan kunci.

Tubuh permintaan

Tubuh permintaan harus diformat sebagai JSON. Bidang-bidang berikut ini didukung, dan semua opsional:

  • homeMobileCountryCode: Kode negara seluler (MCC) untuk jaringan asal perangkat.
  • homeMobileNetworkCode: Kode jaringan seluler (MNC) untuk jaringan asal perangkat.
  • radioType: Tipe radio seluler. Nilai-nilai yang didukung adalah lte, gsm, cdma, dan wcdma. Meskipun opsional, bidang ini harus disertakan jika nilai tersedia, agar hasilnya lebih akurat.
  • carrier: Nama operator.
  • considerIp: Menetapkan apakah akan kembali ke geolokasi IP jika sinyal WiFi dan menara BTS tidak tersedia. Perhatikan, alamat IP dalam header permintaan mungkin bukan IP perangkat. Default-nya adalah true. Setel considerIp ke false untuk menonaktifkan fungsi kembali.
  • cellTowers: Larik objek menara BTS. Lihat bagian Objek Menara BTS di bawah ini.
  • wifiAccessPoints: Sebuah larik objek titik akses WiFi. Lihat bagian Objek Titik Akses WiFi di bawah ini.
{
  "homeMobileCountryCode": 310,
  "homeMobileNetworkCode": 410,
  "radioType": "gsm",
  "carrier": "Vodafone",
  "considerIp": "true",
  "cellTowers": [
    // See the Cell Tower Objects section below.
  ],
  "wifiAccessPoints": [
    // See the WiFi Access Point Objects section below.
  ]
}

Objek menara BTS

Tubuh permintaan larik cellTowers berisi nol atau beberapa objek menara BTS.

  • cellId (diperlukan): Identifier unik seluler. Di GSM, ini adalah Cell ID (CID); jaringan CDMA menggunakan Base Station ID (BID). Jaringan WCDMA menggunakan UTRAN/GERAN Cell Identity (UC-Id), merupakan nilai 32-bit yang mengabungkan Radio Network Controller (RNC) dan Cell ID. Hanya menetapkan nilai Cell ID 16-bit di jaringan WCDMA bisa mengembalikan hasil yang tidak akurat.
  • locationAreaCode (diperlukan): Kode Area Lokasi (Location Area Code/LAC) untuk jaringan GSM dan WCDMA. ID Jaringan (Network ID/NID) untuk jaringan CDMA.
  • mobileCountryCode (diperlukan): Kode Negara Seluler (Mobile Country Code/MCC) menara BTS.
  • mobileNetworkCode (diperlukan): Kode Jaringan Seluler menara BTS. Ini adalah MNC untuk GSM dan WCDMA; CDMA menggunakan System ID (SID).

Bidang opsional berikut saat ini tidak digunakan, namun bisa disertakan jika nilainya tersedia.

  • age: Jumlah milidetik sejak seluler ini menjadi ponsel utama. Jika age adalah 0, cellId akan menyatakan pengukuran saat ini.
  • signalStrength: Kekuatan sinyal radio diukur dalam dBm.
  • timingAdvance: Nilai kemajuan waktu.

Di bawah ini adalah contoh objek menara BTS GSM.

{
  "cellTowers": [
    {
      "cellId": 42,
      "locationAreaCode": 415,
      "mobileCountryCode": 310,
      "mobileNetworkCode": 410,
      "age": 0,
      "signalStrength": -60,
      "timingAdvance": 15
    }
  ]
}

Di bawah ini adalah contoh objek menara BTS WCDMA.

{
  "cellTowers": [
    {
      "cellId": 21532831,
      "locationAreaCode": 2862,
      "mobileCountryCode": 214,
      "mobileNetworkCode": 7
    }
  ]
}

Objek titik akses WiFi

Tubuh permintaan larik wifiAccessPoints harus berisi dua atau beberapa objek titik akses WiFi. macAddress diperlukan; semua bidang lainnya opsional.

  • macAddress: (diperlukan) Alamat MAC simpul WiFi. Pemisah harus berupa : (titik dua).
  • signalStrength: Kekuatan sinyal saat ini yang diukur dalam dBm.
  • age: Jumlah milidetik sejak titik akses ini dideteksi.
  • channel: Saluran yang digunakan klien untuk berkomunikasi dengan titik akses.
  • signalToNoiseRatio: Rasio sinyal dan kebisingan saat ini yang diukur dalam dB.

Contoh objek titik akses WiFi ditunjukkan di bawah ini.

{
  "macAddress": "00:25:9c:cf:1c:ac",
  "signalStrength": -43,
  "age": 0,
  "channel": 11,
  "signalToNoiseRatio": 0
}

Respons Geolocation

Permintaan geolokasi yang berhasil akan mengembalikan respons berformat-JSON yang mendefinisikan lokasi dan radius.

  • location: Garis lintang dan garis bujur yang diperkirakan pengguna, dalam derajat. Berisi satu subbidang lat dan satu lng.
  • accuracy: Akurasi lokasi yang diperkirakan, dalam meter. Ini menyatakan radius lingkaran di sekitar location yang diberikan.
{
  "location": {
    "lat": 51.0,
    "lng": -0.1
  },
  "accuracy": 1200.4
}

Kesalahan

Jika terjadi kesalahan, tubuh respons kesalahan format standar akan dikembalikan dan kode status HTTP akan disetel ke status kesalahan.

Respons berisi sebuah objek dengan satu objek error bersama kunci berikut:

  • code: Proses ini sama seperti status HTTP respons.
  • message: Keterangan singkat mengenai kesalahan.
  • errors: Daftar kesalahan yang terjadi. Setiap kesalahan berisi identifier untuk tipe kesalahan (reason) dan keterangan singkat (message).

Misalnya, mengirim JSON yang tidak valid akan mengembalikan kesalahan berikut:

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "parseError",
    "message": "Parse Error",
   }
  ],
  "code": 400,
  "message": "Parse Error"
 }
}

Kemungkinan kesalahan meliputi:

Alasan Domain Kode Status HTTP Keterangan
dailyLimitExceeded usageLimits 403 Anda telah melebihi batas harian.
keyInvalid usageLimits 400 Kunci API Anda tidak berlaku untuk Google Maps Geolocation API. Pastikan Anda telah menyertakan kunci selengkapnya, dan telah membeli API atau telah mengaktifkan penagihan serta mengaktifkan API untuk memperoleh kuota gratis.
userRateLimitExceeded usageLimits 403 Anda telah melebihi batas permintaan per detik per pengguna yang telah Anda konfigurasikan dalam Google API Console. Batas ini harus dikonfigurasi untuk mencegah satu atau sekelompok kecil pengguna menghabiskan kuota harian Anda, dan sekaligus tetap memungkinkan akses yang semestinya untuk semua pengguna.
notFound geolocation 404 Permintaan valid, namun tidak ada hasil yang dikembalikan.
parseError global 400 Tubuh permintaan bukan JSON yang valid. Lihat bagian Tubuh Permintaan untuk mengetahui detail setiap bidang.

Permintaan contoh

Jika Anda ingin mencoba Google Maps Geolocation API dengan data contoh, simpan JSON berikut ke file:

{
  "considerIp": "false",
  "wifiAccessPoints": [
    {
        "macAddress": "00:25:9c:cf:1c:ac",
        "signalStrength": -43,
        "signalToNoiseRatio": 0
    },
    {
        "macAddress": "00:25:9c:cf:1c:ad",
        "signalStrength": -55,
        "signalToNoiseRatio": 0
    }
  ]
}

Anda nanti bisa menggunakan cURL untuk membuat permintaan dari baris perintah:

$ curl -d @your_filename.json -H "Content-Type: application/json" -i "https://www.googleapis.com/geolocation/v1/geolocate?key=YOUR_API_KEY"

Respons untuk alamat Mac di atas terlihat seperti ini:

{
  "location": {
    "lat": 33.3632256,
    "lng": -117.0874871
  },
  "accuracy": 20
}

(Lihat Dapatkan Kunci jika Anda tidak memiliki kunci API.)

Untuk pengujian tambahan, Anda bisa mendapatkan informasi dari perangkat Android menggunakan Google Places API for Android dan Android Location API, dan dari perangkat iOS menggunakan Google Places API for iOS.

Pertanyaan Umum (FAQ)

Mengapa saya mendapatkan radius accuracy yang sangat besar dalam respons Geolocation?

Jika respons Geolocation Anda menampilkan nilai yang sangat tinggi dalam bidang accuracy, mungkin layanan melakukan geolokasi berdasarkan IP permintaan, bukannya titik WiFi atau menara BTS. Hal ini bisa terjadi jika tidak ada menara BTS atau titik akses yang valid atau dikenali.

Untuk memastikan masalah ini, setel considerIp ke false dalam permintaan Anda. Jika responsnya adalah 404, berarti bisa dipastikan bahwa objek wifiAccessPoints dan cellTowers Anda tidak bisa dicari geolokasinya.

Kirim masukan tentang...

Google Maps Geolocation API
Google Maps Geolocation API
Butuh bantuan? Kunjungi halaman dukungan kami.