Respons dan permintaan geolokasi

Permintaan Geolocation

Permintaan geolokasi 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. key adalah kunci API aplikasi Anda. Kunci ini mengidentifikasi aplikasi Anda untuk tujuan pengelolaan kuota. Pelajari cara mendapatkan kunci.

Isi permintaan

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

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

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

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

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 yang valid: 0–65535.
• Jaringan CDMA (2G) menggunakan ID Stasiun Pemancar (BID) 16-bit apa adanya. Rentang yang valid: 0–65535.
• Jaringan WCDMA (3G) menggunakan Identitas Sel UTRAN/GERAN (UC-ID), yang merupakan nilai bilangan bulat 28 bit yang menggabungkan ID 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 E-UTRAN Cell Identity (ECI), yang merupakan nilai bilangan bulat 28-bit yang menggabungkan E-UTRAN Node B Identifier (eNBId) 20-bit dan ID Sel (CID) 8-bit.
  Formula: enb_id << 8 | cid.
  Rentang yang 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 kebijaksanaan Google, dapat memotong angka agar sesuai dengan rentang yang didokumentasikan, menyimpulkan koreksi pada 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 newRadioCellId 64-bit untuk meneruskan ID sel jaringan ke Geolocation API.

• Jaringan NR (5G) menggunakan New Radio Cell Identity (NCI) 36-bit apa adanya.
  Rentang yang 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 terhadap permintaan sebelumnya akan terlihat seperti ini:

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

Objek titik akses WiFi

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

Contoh objek titik akses Wi-Fi, yang merupakan bagian dari isi permintaan, ditunjukkan di bawah ini.

{
  ...
  
  "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

Jika Anda ingin mencoba Geolocation API dengan data sampel, 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
    }
  ]
}

Anda kemudian 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
}

Menghapus titik akses Wi-Fi yang tidak digunakan

Menghapus objek titik akses Wi-Fi dengan macAddress yang merupakan alamat broadcast (FF:FF:FF:FF:FF:FF) atau dicadangkan oleh IANA dapat meningkatkan rasio keberhasilan panggilan API Geolocation yang menggunakan Wi-Fi sebagai input. Jika, setelah pemfilteran, dapat ditentukan bahwa panggilan API Geolocation tidak akan berhasil, mitigasi seperti menggunakan sinyal lokasi yang lebih lama atau AP Wi-Fi dengan sinyal yang lebih lemah dapat digunakan. Pendekatan ini merupakan kompromi antara kebutuhan aplikasi Anda akan perkiraan lokasi serta persyaratan presisi dan perolehannya. Teknik pemfilteran berikut menunjukkan cara memfilter input, tetapi tidak menunjukkan mitigasi yang dapat 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 Geolokasi dapat dikumpulkan dari array string macAddress bernama macs:

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")));
    

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')]
    

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');
    

Dengan menggunakan filter ini, hanya 1c:34:56:78:9a:bc yang tersisa dalam daftar. Karena daftar ini memiliki kurang dari 2 alamat MAC Wi-Fi, 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: Perkiraan koordinat lintang dan bujur pengguna, dalam derajat. Berisi satu subkolom lat dan satu subkolom lng.
• accuracy: Akurasi estimasi lokasi, dalam meter. Ini mewakili radius lingkaran di sekitar location yang diberikan.

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

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

• Titik akses Wi-Fi: Jika permintaan menyertakan dua atau beberapa 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 Wi-Fi tidak tersedia atau tidak memadai, API akan menggunakan cellTowers untuk lokasi. Akurasi bervariasi secara signifikan 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. Radiusnya biasanya dalam rentang ratusan meter, dan dapat mencapai beberapa ribu meter di area dengan cakupan menara BTS yang jarang. Untuk sel makro, radius akurasi di bawah 100 meter jarang tercapai. Akurasi umumnya lebih tinggi untuk menara BTS dengan sinyal kuat. Sinyal 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 Wi-Fi atau menara BTS yang dapat diidentifikasi lokasinya, 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 Memecahkan masalah.