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 pengelolaan kuota. Pelajari cara mendapatkan kunci.
Isi permintaan
Tubuh 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 System ID (SID) |
Rentang yang valid untuk MNC: 0–999. Rentang yang valid untuk SID: 0–32767. |
radioType |
string |
Tipe radio seluler. Nilai yang didukung adalah gsm , cdma , wcdma , lte , dan nr . |
Meskipun bersifat opsional, kolom ini harus selalu disertakan jika jenis radio
diketahui oleh klien. Jika kolom dihapus, Geolocation API akan ditetapkan secara default ke gsm ,
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 WiFi dan menara BTS tidak ada, kosong, atau tidak cukup untuk memperkirakan lokasi perangkat. | Default-nya adalah true . Tetapkan considerIp ke
false untuk mencegah penggantian. |
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": "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 | Jenis JSON | Deskripsi | Catatan |
---|---|---|---|
cellId |
number (uint32 ) |
Identifier unik seluler. | 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 yang valid dengan gsm , cdma , wcdma , dan
lte : 0–65535.Rentang yang 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 System ID (SID). |
Wajib. Rentang yang valid untuk MNC: 0–999. Rentang yang valid untuk SID: 0–32767. |
Kolom opsional berikut tidak digunakan, tetapi dapat disertakan jika value tersedia.
Kolom | Jenis JSON | Deskripsi | Catatan |
---|---|---|---|
age |
number (uint32 ) |
Jumlah milidetik sejak seluler ini menjadi ponsel utama. | Jika usia adalah 0, cellId atau newRadioCellId menunjukkan pengukuran
saat ini. |
signalStrength |
number (double ) |
Kekuatan sinyal radio diukur dalam dBm. | |
timingAdvance |
number (double ) |
Nilai kemajuan waktu. |
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. Rentang valid: 0–65535.
- Jaringan CDMA (2G) menggunakan ID Stasiun Dasar (BID) 16-bit sebagaimana adanya. Rentang valid: 0–65535.
- Jaringan WCDMA (3G) menggunakan UTRAN/GERAN Cell Identity (UC-ID), yang merupakan nilai bilangan bulat 28-bit
yang menggabungkan Radio Network Controller Identifier (RNC-ID) 12-bit dan
Cell ID (CID) 16-bit.
Formula:rnc_id << 16 | cid
.
Rentang yang valid: 0–268435455.
Catatan: Hanya menetapkan 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 Identifier B E-UTRAN Node B (eNBId) 20-bit dan Cell ID (CID) 8 bit.
Formula:enb_id << 8 | cid
.
Rentang yang valid: 0–268435455.
Catatan: Jika hanya menentukan nilai Cell ID 8 bit di jaringan LTE, hasil yang ditampilkan akan salah atau nol.
Menempatkan nilai di luar rentang ini dalam permintaan API dapat menyebabkan perilaku yang tidak ditentukan. Atas diskresi Google, API dapat memotong angka agar sesuai dengan rentang yang didokumentasikan, menyimpulkan
koreksi ke radioType
, atau menampilkan hasil NOT_FOUND
tanpa
indikator apa pun 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 selulernya lebih panjang dari 32 bit, akan 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.
Di bawah ini adalah contoh objek menara BTS NR.
{ "cellTowers": [ { "newRadioCellId": 68719476735, "mobileCountryCode": 310, "mobileNetworkCode": 410, "age": 0, "signalStrength": -60, } ] }
Objek titik akses WiFi
Array wifiAccessPoints
isi permintaan harus berisi dua
atau lebih objek titik akses Wi-Fi. macAddress
wajib ada; semua kolom lainnya bersifat opsional.
Kolom | Jenis JSON | Deskripsi | Catatan |
---|---|---|---|
macAddress |
string |
Alamat MAC node Wi-Fi. Ini biasanya disebut BSS, BSSID atau alamat MAC. |
Wajib.String heksadesimal yang dipisahkan titik dua (: ).
Hanya alamat MAC yang dikelola secara universal yang dapat ditemukan melalui API. Alamat MAC lain akan dibuang secara diam-diam dan dapat menyebabkan permintaan API menjadi kosong secara efektif. Untuk mengetahui detailnya, lihat Melepaskan 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 dari -128 hingga -10 dBm. Pastikan untuk menyertakan tanda minus. |
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 kebisingan saat ini yang diukur dalam dB. |
Contoh objek titik akses WiFi ditampilkan di bawah ini.
{ "macAddress": "9c:1c:12:b0:45:f1", "signalStrength": -43, "signalToNoiseRatio": 0, "channel": 11, "age": 0 }
Permintaan contoh
Jika Anda ingin mencoba Geolocation API dengan contoh data, simpan JSON berikut ke file:
{ "considerIp": "false", "wifiAccessPoints": [ { "macAddress": "3c:37:86:5d:75:d4", "signalStrength": -35, "signalToNoiseRatio": 0 }, { "macAddress": "94:b4:0f:fd:c1:40", "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.4241876, "lng": -122.0917381 }, "accuracy": 32.839 }
Melepaskan 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 estimasi lokasi serta persyaratan presisi dan perolehannya. Teknik pemfilteran berikut menunjukkan cara memfilter
input, tetapi tidak menunjukkan mitigasi yang mungkin Anda lakukan, sebagai engineer
aplikasi, memilih untuk menerapkan.
Alamat MAC yang dikelola secara lokal bukan merupakan sinyal lokasi yang berguna untuk API dan otomatis dihapus dari permintaan. Anda dapat menghapus alamat MAC ini
dengan memastikan bahwa bit kedua paling tidak signifikan dari
byte macAddress
yang paling signifikan adalah 0
, misalnya
2
dalam
02:00:00:00:00:00
. Alamat MAC siaran (FF:FF:FF:FF:FF:FF
) adalah contoh alamat MAC yang berguna untuk dikecualikan oleh filter ini.
Rentang alamat MAC antara 00:00:5E:00:00:00
dan 00:00:5E:FF:FF:FF
dicadangkan untuk IANA dan sering digunakan untuk pengelolaan jaringan dan fungsi multicast yang menghalangi 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');
Penggunaan filter ini hanya akan menghasilkan 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 menentukan lokasi dan radius.
location
: Perkiraan koordinat lintang dan bujur pengguna, dalam derajat. Berisi satu subkolomlat
dan satu subkolomlng
.accuracy
: Akurasi perkiraan lokasi, dalam meter. Ini mewakili radius lingkaran di sekitarlocation
yang ditentukan.
{ "location": { "lat": 37.421875199999995, "lng": -122.0851173 }, "accuracy": 120 }