Pengantar
Geolocation API mengembalikan lokasi dan radius akurasi berdasarkan informasi tentang menara BTS dan node WiFi yang dapat dideteksi oleh klien seluler. Dokumen ini menjelaskan protokol yang digunakan untuk mengirim data ini ke server dan menampilkan respons kepada klien.
Komunikasi dilakukan melalui HTTPS menggunakan POST. Permintaan dan respons diformat sebagai JSON, dan jenis konten keduanya adalah application/json
.
Sebelum memulai
Sebelum mulai mengembangkan aplikasi dengan Geolocation API, tinjau persyaratan autentikasi (Anda memerlukan kunci API) dan informasi penggunaan dan penagihan API (Anda perlu mengaktifkan penagihan pada project Anda).
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, 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 home 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 home 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 bersifat opsional, kolom ini harus selalu disertakan jika jenis radio diketahui oleh klien. Jika kolom dihilangkan, Geolocation API akan 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 Wi-Fi dan menara BTS tidak ada, kosong, atau tidak cukup untuk memperkirakan lokasi perangkat. | Default-nya adalah true . Setel considerIp ke false untuk menonaktifkan penggantian. |
cellTowers |
array |
Larik objek menara BTS. | Lihat bagian Objek Menara Seluler di bawah ini. |
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 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 | 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 selId 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 , yang bersifat 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 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 saat ini 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 kelanjutan 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 ID Sel (CID) 16-bit apa adanya. Rentang yang valid: 0–65535.
- Jaringan CDMA (2G) menggunakan Base Station ID (BID) 16-bit sebagaimana adanya. Rentang yang valid: 0–65535.
- Jaringan WCDMA (3G) menggunakan UTRAN/GERAN Cell Identity (UC-ID), yang merupakan nilai integer
28 bit yang menggabungkan 12-bit Radio Network Controller Identifier (RNC-ID) dan 16-bit
Cell ID (CID).
Formula:rnc_id << 16 | cid
.
Rentang yang valid: 0–268435455.
Catatan: Jika Anda hanya menetapkan nilai ID Sel 16-bit di jaringan WCDMA, hasilnya akan 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: Jika Anda hanya menetapkan nilai Cell ID 8 bit di jaringan LTE, hasilnya akan salah atau tidak ada sama sekali.
Menempatkan nilai di luar rentang ini dalam permintaan API dapat menghasilkan perilaku yang tidak ditentukan. API,
atas kebijaksanaan Google, dapat memotong angka agar sesuai dalam rentang yang didokumentasikan, menyimpulkan
koreksi ke radioType
, atau menampilkan hasil NOT_FOUND
tanpa
indikator apa pun dalam respons.
Berikut 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 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.
Berikut 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 beberapa objek titik akses WiFi atau lebih. macAddress
wajib diisi; semua
kolom lainnya bersifat opsional.
Kolom | Jenis JSON | Deskripsi | Catatan |
---|---|---|---|
macAddress |
string |
Alamat MAC node WiFi. Alamat ini biasanya disebut alamat BSS, BSSID, atau MAC. | Wajib. String heksadesimal : (titik dua) yang dipisahkan. |
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 derau 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 }
Respons Geolocation
Permintaan geolokasi yang berhasil akan menampilkan respons berformat JSON yang menentukan lokasi dan radius.
location
: Estimasi lintang dan bujur pengguna, dalam derajat. Berisi satu subkolomlat
dan satulng
.accuracy
: Akurasi perkiraan lokasi, dalam meter. Ini merepresentasikan radius lingkaran di sekitarlocation
yang diberikan.
{ "location": { "lat": 37.421875199999995, "lng": -122.0851173 }, "accuracy": 120 }
Error
Jika terjadi error, isi respons error format standar akan ditampilkan dan kode status HTTP akan disetel ke status error.
Respons berisi objek dengan satu objek error
dengan
kunci berikut:
code
: Ini sama dengan status HTTP respons.message
: Deskripsi singkat error.errors
: Daftar error yang terjadi. Setiap error berisi ID untuk jenis error (reason
) dan deskripsi singkat (message
).
Misalnya, mengirim JSON yang tidak valid akan mengembalikan kesalahan berikut:
{ "error": { "errors": [ { "domain": "global", "reason": "parseError", "message": "Parse Error", } ], "code": 400, "message": "Parse Error" } }
Kemungkinan kesalahan meliputi:
Alasan | Domain | Kode Status HTTP | Deskripsi |
---|---|---|---|
dailyLimitExceeded |
usageLimits |
403 | Anda telah melampaui batas harian. |
keyInvalid |
usageLimits |
400 | Kunci API Anda tidak valid untuk Geolocation API. Pastikan Anda telah menyertakan seluruh kunci, dan telah membeli API atau mengaktifkan penagihan dan mengaktifkan API untuk mendapatkan kuota tanpa biaya. |
userRateLimitExceeded |
usageLimits |
403 | Anda telah melampaui batas permintaan yang dikonfigurasi di Google Cloud Console. Batas ini biasanya ditetapkan sebagai permintaan per hari, permintaan per 100 detik, dan permintaan per 100 detik per pengguna. Batas ini harus dikonfigurasi untuk mencegah satu atau sekelompok kecil pengguna menghabiskan kuota harian Anda, sambil tetap mengizinkan akses yang wajar untuk semua pengguna. Lihat Membatasi Penggunaan API untuk mengonfigurasi batas ini. |
notFound |
geolocation |
404 | Permintaan valid, namun tidak ada hasil yang dikembalikan. |
parseError |
global |
400 | Tubuh permintaan bukan JSON yang valid. Lihat bagian Isi Permintaan untuk mengetahui detail setiap kolom. |
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": "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 di atas terlihat seperti ini:
{ "location": { "lat": 37.4241876, "lng": -122.0917381 }, "accuracy": 32.839 }
(Lihat Mendapatkan Kunci API jika Anda tidak memiliki kunci API.)
Untuk pengujian tambahan, Anda dapat mengumpulkan informasi dari perangkat Android menggunakan Places SDK for Android dan Android Location API, dan dari perangkat iOS menggunakan Places SDK for iOS.
Pertanyaan umum (FAQ)
Mengapa saya mendapatkan radius accuracy
yang sangat besar dalam
respons Geolokasi?
Jika respons Geolokasi menampilkan nilai yang sangat tinggi di kolom accuracy
, layanan mungkin melakukan geolokasi berdasarkan IP permintaan, bukan titik WiFi atau menara BTS. Hal ini dapat terjadi jika tidak ada menara BTS atau titik akses yang valid atau dikenali.
Untuk mengonfirmasi bahwa ini adalah masalahnya, tetapkan considerIp
ke
false
dalam permintaan Anda. Jika responsnya adalah 404
,
Anda telah mengonfirmasi bahwa objek wifiAccessPoints
dan
cellTowers
Anda tidak dapat ditemukan geolokasi.