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 keperluan manajemen 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 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

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

Kolom 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 Cell ID (CID) 16-bit sebagaimana adanya. Rentang valid: 0–65535.
• Jaringan CDMA (2G) menggunakan ID Stasiun Pangkalan (BID) 16-bit sebagaimana adanya. Rentang yang valid: 0–65535.
• Jaringan WCDMA (3G) menggunakan UTRAN/GERAN Cell Identity (UC-ID), yang merupakan nilai bilangan bulat 28-bit yang menggabungkan ID Pengontrol Jaringan Radio (RNC-ID) 12-bit dan Cell ID 16-bit (CID).
  Formula: rnc_id << 16 | cid.
  Rentang yang valid: 0–268435455.
  Catatan: Hanya menentukan nilai Cell ID 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 20-bit E-UTRAN Node B Identifier (eNBId) dan Cell ID (CID) 8-bit.
  Formula: enb_id << 8 | cid.
  Rentang yang valid: 0–268435455.
  Catatan: Hanya menentukan nilai Cell ID 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 memotong angka agar sesuai dengan rentang yang didokumentasikan, menyimpulkan koreksi pada radioType, atau menampilkan hasil NOT_FOUND tanpa indikator dalam respons.

Di bawah ini adalah contoh objek menara BTS LTE.

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

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 sebagaimana adanya.
  Rentang yang valid: 0–68719476735.

Contoh objek menara BTS NR adalah sebagai berikut.

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

Objek titik akses WiFi

Array wifiAccessPoints isi permintaan harus berisi dua objek titik akses WiFi atau lebih yang mewakili perangkat titik akses yang berbeda secara fisik. macAddress wajib diisi; semua kolom lainnya bersifat opsional.

Contoh objek titik akses WiFi ditampilkan di bawah ini.

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

Permintaan contoh

Jika Anda ingin mencoba Geolocation API dengan contoh data, simpan JSON berikut ke dalam 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 terlihat seperti ini:

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

Menghapus titik akses WiFi yang tidak digunakan

Menghapus objek titik akses Wi-Fi dengan macAddress yang dikelola secara lokal dapat meningkatkan tingkat keberhasilan panggilan Geolocation API yang menggunakan Wi-Fi sebagai input. Jika, setelah pemfilteran, dapat ditentukan bahwa panggilan Geolocation API tidak akan berhasil, mitigasi seperti menggunakan sinyal lokasi lama atau AP Wi-Fi dengan sinyal yang lebih lemah dapat digunakan. Pendekatan ini merupakan kompromi antara kebutuhan aplikasi Anda akan perkiraan lokasi dan persyaratan presisi dan perolehannya. Teknik pemfilteran berikut menunjukkan cara memfilter input, tetapi tidak menampilkan mitigasi yang dapat Anda pilih untuk diterapkan sebagai engineer aplikasi.

Alamat MAC yang dikelola secara lokal bukanlah sinyal lokasi yang berguna untuk API dan akan dihapus secara diam-diam dari permintaan. Anda dapat menghapus alamat MAC tersebut dengan memastikan bahwa bit kedua yang paling tidak signifikan dari byte paling signifikan macAddress adalah 0, misalnya 1 bit yang diwakili oleh 2 di 02:00:00:00:00:00. Alamat MAC siaran (FF:FF:FF:FF:FF:FF) adalah contoh alamat MAC yang akan berguna dikecualikan oleh filter ini.

Rentang alamat MAC antara 00:00:5E:00:00:00 dan 00:00:5E:FF:FF:FF disediakan untuk IANA dan sering digunakan untuk pengelolaan jaringan dan fungsi multicast yang mencegah penggunaannya 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 = {"12:34:56:78:9a:bc", "1c:34:56:78:9a:bc", "00:00:5e:00:00:01"};
ArrayList<String> _macs = new ArrayList<>(Arrays.asList(macs));
_macs.removeIf(m -> !(0 == (2 & Integer.parseInt(m.substring(1, 2), 16))
                      && !m.substring(0, 8).toUpperCase().equals("00:00:5E")));
    

macs = ['12:34:56:78:9a:bc', '1c:34:56:78:9a:bc', '00:00:5e:00:00:01']
macs = [m for m in macs if (0 == (2 & int(m[1], 16)) and m[:8].upper() != '00:00:5E')]
    

macs = ['12:34:56:78:9a:bc', '1c:34:56:78:9a:bc', '00:00:5e:00:00:01'];
macs = macs.filter(m => 0 === (2 & Number.parseInt(m[1], 16))
                           && 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 (notFound) HTTP 404 akan ditampilkan.

Respons Geolocation

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

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

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