Respons dan permintaan geolokasi

Permintaan Geolocation

Permintaan Geolocation dikirim menggunakan POST ke URL berikut:

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

Anda harus menentukan kunci dalam permintaan, yang disertakan sebagai nilai parameter key. A key adalah kunci API aplikasi Anda. Kunci ini mengidentifikasi aplikasi Anda untuk tujuan pengelolaan kuota management. Pelajari cara mendapatkan kunci.

Isi permintaan

Isi permintaan harus diformat sebagai JSON. Jika isi permintaan tidak disertakan, hasilnya akan ditampilkan berdasarkan alamat IP lokasi permintaan. Kolom berikut didukung, dan semua kolom bersifat opsional, kecuali jika dinyatakan lain:

Kolom	Jenis JSON	Deskripsi	Catatan
homeMobileCountryCode	number (uint32)	Kode negara seluler (MCC) untuk jaringan rumah perangkat.	Didukung untuk radioType gsm (default), wcdma, lte dan nr; tidak digunakan untuk cdma. Rentang valid: 0–999.
homeMobileNetworkCode	number (uint32)	Kode Jaringan Seluler untuk jaringan rumah perangkat. Ini adalah MNC untuk GSM, WCDMA, LTE, dan NR. CDMA menggunakan ID Sistem (SID)	Rentang valid untuk MNC: 0–999. Rentang valid untuk SID: 0–32767.
radioType	string	Tipe radio seluler. Nilai yang didukung adalah gsm, cdma, wcdma, lte dan nr.	Meskipun kolom ini bersifat opsional, kolom ini harus selalu disertakan jika jenis radio diketahui oleh klien. Jika kolom dihilangkan, Geolocation API akan menggunakan gsm secara default, yang akan menghasilkan hasil yang tidak valid atau nol jika jenis radio yang diasumsikan salah.
carrier	string	Nama operator.
considerIp	boolean	Menentukan apakah akan kembali ke geolokasi IP jika sinyal menara seluler dan WiFi tidak ada, kosong, atau tidak cukup untuk memperkirakan lokasi perangkat.	Default-nya adalah true. Tetapkan considerIp ke false untuk mencegah kembali.
cellTowers	array	Larik objek menara BTS.	Lihat bagian Objek Menara BTS di bawah.
wifiAccessPoints	array	Sebuah larik objek titik akses WiFi.	Lihat bagian Objek Titik Akses WiFi di bawah.

Contoh isi permintaan Geolocation API ditampilkan di bawah.

{
  "homeMobileCountryCode": 310,
  "homeMobileNetworkCode": 410,
  "radioType": "lte",
  "carrier": "Vodafone",
  "considerIp": true,
  "cellTowers": [
    // See the Cell Tower Objects section below.
  ],
  "wifiAccessPoints": [
    // See the WiFi Access Point Objects section below.
  ]
}

Objek menara BTS

Larik cellTowers isi permintaan berisi nol atau beberapa objek menara BTS.

Kolom	Jenis JSON	Deskripsi	Catatan
cellId	number (uint32)	ID unik sel.	Wajib untuk radioType gsm (default), cdma, wcdma dan lte; ditolak untuk nr. Lihat bagian Menghitung cellId di bawah, yang juga mencantumkan rentang nilai yang valid untuk setiap jenis radio.
newRadioCellId	number (uint64)	ID unik sel NR (5G).	Wajib untuk radioType nr; ditolak untuk jenis lainnya Lihat bagian Menghitung newRadioCellId di bawah, yang juga mencantumkan rentang nilai yang valid untuk kolom tersebut.
locationAreaCode	number (uint32)	Kode Area Lokasi (LAC) untuk jaringan GSM dan WCDMA. ID Jaringan (NID) untuk jaringan CDMA. Kode Area Pelacakan (TAC) untuk jaringan LTE dan NR.	Wajib untuk radioType gsm (default) dan cdma, opsional untuk nilai lainnya. Rentang valid dengan gsm, cdma, wcdma dan lte: 0–65535. Rentang valid dengan nr: 0–16777215.
mobileCountryCode	number (uint32)	Kode Negara Seluler (MCC) menara BTS.	Wajib untuk radioType gsm (default), wcdma, lte dan nr; tidak digunakan untuk cdma. Rentang valid: 0–999.
mobileNetworkCode	number (uint32)	Kode Jaringan Seluler menara BTS. Ini adalah MNC untuk GSM, WCDMA, LTE, dan NR. CDMA menggunakan ID Sistem (SID).	Wajib. Rentang valid untuk MNC: 0–999. Rentang valid untuk SID: 0–32767.

Kolom opsional berikut tidak digunakan, tetapi dapat disertakan jika nilainya tersedia.

Kolom	Jenis JSON	Deskripsi	Catatan
age	number (uint32)	Jumlah milidetik sejak seluler ini menjadi ponsel utama.	Jika usia adalah 0, cellId atau newRadioCellId mewakili pengukuran saat ini.
signalStrength	number (double)	Kekuatan sinyal radio diukur dalam dBm.
timingAdvance	number (double)	Nilai waktu lanjutan.

Menghitung cellId

Jenis radio sebelum NR (5G) menggunakan kolom cellId 32-bit untuk meneruskan ID sel jaringan ke Geolocation API.

• Jaringan GSM (2G) menggunakan ID Sel (CID) 16-bit apa adanya. Rentang valid: 0–65535.
• Jaringan CDMA (2G) menggunakan ID Stasiun Basis (BID) 16-bit apa adanya. Rentang valid: 0–65535.
• Jaringan WCDMA (3G) menggunakan Identitas Sel UTRAN/GERAN (UC-ID), yang merupakan nilai bilangan bulat 28-bit yang menggabungkan Pengidentifikasi Pengontrol Jaringan Radio (RNC-ID) 12-bit dan ID Sel (CID) 16-bit .
  Formula: rnc_id << 16 | cid.
  Rentang valid: 0–268435455.
  Catatan: Menentukan hanya nilai ID Sel 16-bit di jaringan WCDMA akan menghasilkan hasil yang salah atau nol.
• Jaringan LTE (4G) menggunakan Identitas Sel E-UTRAN (ECI), yang merupakan nilai bilangan bulat 28-bit yang menggabungkan Pengidentifikasi Node B E-UTRAN (eNBId) 20-bit dan ID Sel (CID) 8-bit.
  Formula: enb_id << 8 | cid.
  Rentang valid: 0–268435455.
  Catatan: Menentukan hanya nilai ID Sel 8-bit di jaringan LTE akan menghasilkan hasil yang salah atau nol.

Menempatkan nilai di luar rentang ini dalam permintaan API dapat menyebabkan perilaku yang tidak ditentukan. API, atas pertimbangan Google, dapat memangkas angka sehingga sesuai dengan rentang yang didokumentasikan, menyimpulkan koreksi ke radioType, atau menampilkan hasil NOT_FOUND tanpa indikator apa pun dalam respons.

Contoh objek menara BTS LTE, yang merupakan bagian dari isi permintaan, ada di bawah.

{
  ...

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

Respons untuk permintaan sebelumnya akan terlihat seperti ini:

{
  "location": {
    "lat": 37.7801129,
    "lng": -122.4168229
  },
  "accuracy": 180.052
}

Menghitung newRadioCellId

Jaringan yang lebih baru, yang ID selnya lebih panjang dari 32 bit, menggunakan kolom 64-bit newRadioCellId untuk meneruskan ID sel jaringan ke Geolocation API.

• Jaringan NR (5G) menggunakan Identitas Sel Radio Baru (NCI) 36-bit apa adanya.
  Rentang valid: 0–68719476735.

Contoh objek menara BTS NR, yang merupakan bagian dari isi permintaan, ada di bawah.

{
  ...

  "cellTowers": [
    {
      "newRadioCellId": 68719476735,
      "mobileCountryCode": 310,
      "mobileNetworkCode": 410,
      "age": 0,
      "signalStrength": -60,
    }
  ]
}

Respons untuk permintaan sebelumnya akan terlihat seperti ini:

{
  "location": {
    "lat": 37.7646157,
    "lng": -122.4127361
  },
  "accuracy": 1458.5570522410717
}

Objek titik akses WiFi

Larik wifiAccessPoints isi permintaan harus berisi dua atau lebih objek titik akses WiFi yang mewakili perangkat titik akses stasioner yang secara fisik berbeda. Kolom macAddress wajib diisi. Semua kolom lainnya bersifat opsional. Layanan ini mengabaikan titik akses yang bergerak, seperti yang ada di pesawat dan kereta.

Kolom	Jenis JSON	Deskripsi	Catatan
macAddress	string	Alamat MAC node WiFi. Biasanya disebut alamat BSS, BSSID, atau MAC.	Wajib. String heksadesimal yang dipisahkan koma (:). Hanya alamat MAC yang dikelola secara universal yang dapat ditemukan menggunakan API. Alamat MAC lainnya akan dihilangkan secara diam-diam dan dapat menyebabkan permintaan API menjadi kosong. Untuk mengetahui detailnya, lihat Menghilangkan titik akses WiFi yang tidak berguna.
signalStrength	number (double)	Kekuatan sinyal saat ini yang diukur dalam dBm.	Untuk titik akses WiFi, nilai dBm biasanya -35 atau lebih rendah dan berkisar antara -128 hingga -10 dBm. Pastikan untuk menyertakan tanda minus. Untuk nilai yang lebih besar dari -10 dBm, API akan menampilkan NOT FOUND.
age	number (uint32)	Jumlah milidetik sejak titik akses ini dideteksi.
channel	number (uint32)	Saluran yang digunakan klien untuk berkomunikasi dengan titik akses.
signalToNoiseRatio	number (double)	Rasio sinyal terhadap noise saat ini diukur dalam dB.

Contoh objek titik akses WiFi, yang merupakan bagian dari isi permintaan, ditampilkan di bawah.

{
  ...
  
  "macAddress": "f0:d5:bf:fd:12:ae",
  "signalStrength": -43,
  "signalToNoiseRatio": 0,
  "channel": 11,
  "age": 0
}

Respons untuk permintaan sebelumnya akan terlihat seperti ini:

{
  "location": {
    "lat": 37.7801129,
    "lng": -122.4168229
  },
  "accuracy": 180.052
}

Permintaan contoh

Catatan: Alamat MAC dapat berubah dari waktu ke waktu. Oleh karena itu, contoh di halaman ini dapat menghasilkan pesan error dari API.

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

{
  "considerIp": "false",
  "wifiAccessPoints": [
    {
      "macAddress": "3c:37:86:5d:75:d4",
      "signalStrength": -35,
      "signalToNoiseRatio": 0
    },
    {
      "macAddress": "30:86:2d:c4:29:d0",
      "signalStrength": -35,
      "signalToNoiseRatio": 0
    }
  ]
}

Kemudian, Anda dapat menggunakan curl untuk membuat permintaan dari command line:

$ 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 sebelumnya akan terlihat seperti ini:

{
  "location": {
    "lat": 37.4241173,
    "lng": -122.0915717
  },
  "accuracy": 20
}

Menghilangkan titik akses WiFi yang tidak digunakan

Menghapus objek titik akses WiFi dengan macAddresses yang merupakan alamat siaran (FF:FF:FF:FF:FF:FF) atau dicadangkan oleh IANA dapat meningkatkan tingkat keberhasilan panggilan Geolocation API yang menggunakan WiFi sebagai input. Jika, setelah pemfilteran, dapat ditentukan bahwa panggilan Geolocation API tidak akan berhasil, mitigasi seperti menggunakan sinyal lokasi yang lebih lama atau AP WiFi dengan sinyal yang lebih lemah dapat digunakan. Pendekatan ini merupakan kompromi antara kebutuhan aplikasi Anda untuk perkiraan lokasi dan persyaratan presisi serta recall-nya. Teknik pemfilteran berikut menunjukkan cara memfilter input, tetapi tidak menampilkan mitigasi yang mungkin Anda, sebagai engineer aplikasi, pilih untuk diterapkan.

Rentang alamat MAC antara 00:00:5E:00:00:00 dan 00:00:5E:FF:FF:FF dicadangkan untuk IANA dan sering digunakan untuk fungsi pengelolaan jaringan dan multicast, sehingga tidak dapat digunakan sebagai sinyal lokasi. Anda juga harus menghapus alamat MAC ini dari input ke API.

Misalnya, alamat MAC yang dapat digunakan untuk Geolocation dapat dikumpulkan dari an array of macAddress strings named macs:

Java

String[] macs = {"ff:ff:ff:ff:ff:ff", "1c:34:56:78:9a:bc", "00:00:5e:00:00:01"};
ArrayList<String> _macs = new ArrayList<>(Arrays.asList(macs));
_macs.removeIf(m -> !(!m.toUpperCase().equals("FF:FF:FF:FF:FF:FF")
                      && !m.substring(0, 8).toUpperCase().equals("00:00:5E")));
    

Python

macs = ['ff:ff:ff:ff:ff:ff', '1c:34:56:78:9a:bc', '00:00:5e:00:00:01']
macs = [m for m in macs if (m.upper() != "FF:FF:FF:FF:FF:FF" and m[:8].upper() != '00:00:5E')]
    

JavaScript

macs = ['ff:ff:ff:ff:ff:ff', '1c:34:56:78:9a:bc', '00:00:5e:00:00:01'];
macs = macs.filter(m => m.toUpperCase() !== "FF:FF:FF:FF:FF:FF"
                        && m.substr(0, 8).toUpperCase() !== '00:00:5E');
    

Menggunakan filter ini akan menghasilkan hanya 1c:34:56:78:9a:bc yang tersisa dalam daftar. Karena daftar ini memiliki kurang dari 2 alamat MAC WiFi, permintaan tidak akan berhasil dan respons HTTP 404 (notFound) akan ditampilkan.

Respons Geolocation

Permintaan geolokasi yang berhasil akan menampilkan respons berformat JSON yang menentukan lokasi dan radius.

• location: Koordinat lintang dan bujur perkiraan pengguna dalam derajat. Berisi satu lat dan satu lng subkolom.
• accuracy: Akurasi perkiraan lokasi, dalam meter. Ini mewakili radius lingkaran di sekitar yang diberikan location.

{
  "location": {
    "lat": 37.421875199999995,
    "lng": -122.0851173
  },
  "accuracy": 120
}

API menampilkan lokasi dan radius akurasi berdasarkan sinyal input. Meskipun API dapat menampilkan lokasi yang sangat akurat, akurasi dapat bervariasi bergantung pada sumber, jumlah, kepadatan, dan kekuatan sinyal yang tersedia. Biasanya, Anda dapat memperkirakan radius akurasi berikut:

• Titik akses WiFi: Jika permintaan menyertakan dua atau lebih wifiAccessPoints, radius akurasi yang ditampilkan biasanya sekitar 20 meter. Akurasi meningkat seiring dengan jumlah titik akses dan sinyal yang lebih kuat (diukur dalam dBm), dengan kekuatan sinyal biasanya berkisar antara -100 hingga -20 dBm.
• Menara BTS: Jika informasi WiFi tidak tersedia atau tidak mencukupi, API akan menggunakan cellTowers untuk lokasi. Akurasi sangat bervariasi menurut jenis menara BTS, kekuatan sinyal, dan kepadatan jaringan:
  • Sel makro (jenis yang paling umum, digunakan untuk cakupan area luas ) memberikan akurasi yang lebih rendah. Radius biasanya berada dalam rentang ratusan meter, dan dapat mencapai beberapa ribu meter di area dengan cakupan menara BTS yang jarang. Untuk sel makro, jarang sekali mencapai radius akurasi di bawah 100 meter. Akurasi umumnya lebih tinggi untuk menara BTS dengan sinyal yang kuat. Sinyal yang kuat biasanya > -110 dBm untuk LTE (rentang sinyal -140 hingga -55 dBm), > -100 dBm untuk WCDMA (rentang sinyal -111 hingga -53 dBm), > -100 dBm untuk CDMA (rentang sinyal -120 hingga -40 dBm), dan > -80 dBm untuk GSM (rentang sinyal -121 hingga -1 dBm).
  • Sel kecil (misalnya, femtocell, picocell, atau repeater dalam ruangan) memberikan lokasi berbasis sel yang paling akurat, dengan radius akurasi yang dapat berada dalam rentang 10-30 meter.
• Geolokasi IP: Jika considerIp adalah true dan tidak ada sinyal menara seluler atau WiFi yang dapat dilokasikan secara geografis, API akan memperkirakan lokasi berdasarkan alamat IP permintaan. Metode ini memberikan akurasi terendah, dengan radius yang dapat mencapai ribuan meter. Lihat Mengapa radius akurasi sangat besar? di Panduan pemecahan masalah.