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 atribut Kunci API. Kunci ini mengidentifikasi aplikasi Anda untuk keperluan kuota otomatisasi pengelolaan biaya. Pelajari cara mendapatkan kunci.

Isi permintaan

Tubuh permintaan harus diformat sebagai JSON. Jika isi permintaan tidak disertakan, hasil ditampilkan berdasarkan alamat IP lokasi permintaan. {i>Field<i} berikut adalah 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 mungkin disertakan jika nilai yang tersedia.

Menghitung cellId

Jenis radio sebelum NR (5G) menggunakan kolom cellId 32-bit untuk meneruskan jaringan ID sel 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 valid: 0–65535.
• Jaringan WCDMA (3G) menggunakan UTRAN/GERAN Cell Identity (UC-ID), yang merupakan bilangan bulat 28-bit yang menggabungkan 12-bit Radio Network Controller Identifier (RNC-ID) dan 16-bit ID sel (CID).
  Formula: rnc_id << 16 | cid.
  Rentang valid: 0–268435455.
  Catatan: Hanya menentukan nilai Cell ID 16-bit di jaringan WCDMA menghasilkan hasil yang salah atau nol.
• Jaringan LTE (4G) menggunakan E-UTRAN Cell Identity (ECI), yang merupakan nilai bilangan bulat 28-bit yang menggabungkan ID Node B E-UTRAN 20-bit (eNBId) dan Cell ID (CID) 8-bit.
  Formula: enb_id << 8 | cid.
  Rentang valid: 0–268435455.
  Catatan: Hanya menentukan nilai Cell ID 8-bit di jaringan LTE menyebabkan hasil yang salah atau nol.

Menempatkan nilai di luar rentang ini dalam permintaan API dapat menghasilkan perilaku yang tidak ditentukan. API, atas kebijaksanaan Google, dapat memotong nomor tersebut agar sesuai dengan rentang yang didokumentasikan, koreksi pada radioType, atau tampilkan hasil NOT_FOUND tanpa indikator tertentu dalam respons.

Contoh objek menara BTS LTE ada di bawah ini.

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

Menghitung newRadioCellId

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

• Jaringan NR (5G) menggunakan New Radio Cell Identity (NCI) 36-bit sebagaimana adanya.
  Rentang 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 atau lebih banyak objek titik akses WiFi. 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 Anda 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 sebelumnya terlihat seperti ini:

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

Meletakkan 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 memfilter, dapat ditentukan bahwa panggilan Geolocation API akan tidak berhasil, mitigasi seperti menggunakan sinyal lokasi lama atau WiFi AP dengan sinyal yang lebih lemah dapat digunakan. Pendekatan ini adalah kompromi antara kebutuhan aplikasi atas perkiraan lokasi serta presisi dan perolehannya lainnya. Teknik pemfilteran berikut menunjukkan cara memfilter input, tetapi tidak menunjukkan mitigasi yang dapat Anda lakukan, sebagai insinyur, pilih untuk melamar.

Alamat MAC yang dikelola secara lokal bukanlah sinyal lokasi yang berguna untuk API dan otomatis dihapus dari permintaan. Anda dapat menghapus alamat MAC tersebut dengan memastikan bahwa bit paling tidak signifikan kedua dari Byte macAddress yang paling signifikan adalah 0, misalnya tindakan 1 bit 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 dikecualikan secara berguna oleh filter ini.

Rentang alamat MAC antara 00:00:5E:00:00:00 dan 00:00:5E:FF:FF:FF adalah dicadangkan untuk IANA dan sering digunakan untuk pengelolaan jaringan serta fungsi multicast yang menghalangi penggunaannya sebagai sinyal lokasi. Anda juga harus menghapus alamat MAC dari input ke API.

Misalnya, alamat MAC yang dapat digunakan untuk Geolokasi dapat dikumpulkan dari array string macAddress yang 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');
    

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

Respons Geolocation

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

• location: Perkiraan lintang dan bujur pengguna koordinat, dalam derajat. Berisi satu lat dan satu lng sub-isian.
• accuracy: Keakuratan perkiraan lokasi, di meter. Nilai ini mewakili radius lingkaran di sekitar bidang yang ditentukan location.

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