Halaman ini diterjemahkan oleh Cloud Translation API.

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:

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 yang 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 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 opsional, kolom ini harus selalu disertakan jika jenis radio diketahui oleh klien. Jika kolom ini tidak ada, Geolocation API akan menggunakan nilai default `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 seluler hilang, kosong, atau tidak cukup untuk memperkirakan lokasi perangkat.	Default-nya adalah `true`. Setel `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 Wi-Fi 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

Array cellTowers isi permintaan berisi nol atau lebih 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.
`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 seluler.	Wajib untuk `radioType` `gsm` (default), `wcdma`, `lte`, dan `nr`; tidak digunakan untuk `cdma`. Rentang yang 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 yang valid untuk MNC: 0–999. Rentang yang valid untuk SID: 0–32767.

Kolom opsional berikut tidak digunakan, tetapi dapat disertakan jika nilai 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 penyesuaian waktu.

Menghitung `cellId`

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

Jaringan GSM (2G) menggunakan ID Seluler (CID) 16-bit apa adanya. Rentang valid: 0–65535.
Jaringan CDMA (2G) menggunakan Base Station ID (BID) 16-bit apa adanya. Rentang valid: 0–65535.
Jaringan WCDMA (3G) menggunakan UTRAN/GERAN Cell Identity (UC-ID), yang merupakan nilai integer 28-bit yang menggabungkan Radio Network Controller Identifier (RNC-ID) 12-bit dan Cell ID (CID) 16-bit.Rumus
: rnc_id << 16 | cid.
Rentang yang 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 Cell ID (CID) 8-bit.
Formula: enb_id << 8 | cid.
Rentang yang valid: 0–268435455.
Catatan: Hanya menentukan 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 mengakibatkan perilaku yang tidak terdefinisi. API, atas kebijakan Google, dapat memotong angka tersebut sehingga sesuai dengan rentang yang didokumentasikan, menyimpulkan koreksi pada radioType, atau mengembalikan hasil NOT_FOUND tanpa indikator apa pun dalam respons.

Contoh objek menara seluler LTE, yang merupakan bagian dari badan 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 Identitas Sel Radio Baru (NCI) 36-bit sebagaimana adanya.
Rentang yang valid: 0–68719476735.

Contoh objek menara seluler NR, yang merupakan bagian dari badan 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

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

Kolom	Jenis JSON	Deskripsi	Catatan
`macAddress`	`string`	Alamat MAC node WiFi. Biasanya disebut BSS, BSSID, atau alamat MAC.	Wajib.String heksadesimal yang dipisahkan dengan titik dua (`:`). Hanya alamat MAC yang diatur secara universalyang dapat ditemukan menggunakan API. Alamat MAC lainnya akan dihapus 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 dari -128 hingga -10 dBm. Pastikan untuk menyertakan tanda minus. Untuk nilai yang lebih besar dari -10 dBm, API 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 kebisingan saat ini yang diukur dalam dB.

Contoh objek titik akses Wi-Fi, 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

Jika Anda 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
    }
  ]
}

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 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 yang lebih lama atau AP WiFi dengan sinyal yang lebih lemah dapat digunakan. Pendekatan ini merupakan pertukaran antara kebutuhan aplikasi Anda akan perkiraan lokasi dan persyaratan presisi serta perolehan kembali. Teknik pemfilteran berikut menunjukkan cara memfilter input, tetapi tidak menunjukkan mitigasi yang dapat Anda terapkan sebagai engineer aplikasi.

Alamat MAC yang dikelola secara lokal bukanlah sinyal lokasi yang berguna untuk API dan akan dihilangkan 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 bit 1 yang diwakili oleh 2 dalam 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 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 Geolocation dapat dikumpulkan dari array string macAddress bernama macs:

Java

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

Python

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

JavaScript

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

Menggunakan filter ini hanya akan menghasilkan 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: Perkiraan koordinat lintang dan bujur pengguna, dalam derajat. Berisi satu sub-kolom lat dan satu sub-kolom lng.
accuracy: Akurasi perkiraan lokasi, dalam meter. Ini menunjukkan radius lingkaran di sekitar location yang diberikan.

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