Coğrafi konum istekleri
Coğrafi konum istekleri, aşağıdaki URL'ye POST kullanılarak gönderilir:
https://www.googleapis.com/geolocation/v1/geolocate?key=YOUR_API_KEY
İsteğinizde, key
parametresinin değeri olarak eklenen bir anahtar belirtmelisiniz. key
, uygulamanızın API anahtarıdır. Bu anahtar, kota yönetimi amacıyla uygulamanızı tanımlar. Nasıl anahtar alacağınızı öğrenin.
İstek içeriği
İsteğin gövdesi JSON biçiminde olmalıdır. İsteğin gövdesi dahil edilmezse sonuçlar, istek konumunun IP adresine göre döndürülür. Aşağıdaki alanlar desteklenir ve aksi belirtilmedikçe tüm alanlar isteğe bağlıdır:
Alan | JSON türü | Açıklama | Notlar |
---|---|---|---|
homeMobileCountryCode |
number (uint32 ) |
Cihazın ev ağına ait mobil ülke kodu (MM). | radioType gsm (varsayılan),
wcdma , lte ve nr için desteklenir; cdma için kullanılmaz.Geçerli aralık: 0-999. |
homeMobileNetworkCode |
number (uint32 ) |
Cihazın ev ağına ait Mobil Ağ Kodu.
Bu; GSM, WCDMA, LTE ve NR için MNC'dir. CDMA, Sistem kimliğini (SID) kullanır |
MNC için geçerli aralık: 0-999. SID için geçerli aralık: 0-32767. |
radioType |
string |
Mobil radyo türü. Desteklenen değerler: gsm , cdma , wcdma , lte ve nr . |
Bu alan isteğe bağlı olsa da radyo türü istemci tarafından biliniyorsa her zaman eklenmelidir. Bu alan atlanırsa Geolocation API varsayılan olarak gsm değerine ayarlanır. Bu, varsayılan radyo türünün yanlış olması durumunda geçersiz veya sıfır sonuç alır. |
carrier |
string |
Kargo şirketinin adı. | |
considerIp |
boolean |
Kablosuz ağ ve baz istasyonu sinyalleri eksik, boş veya cihaz konumunu tahmin etmek için yeterli değilse IP coğrafi konumunu temel alıp almayacağını belirtir. | Varsayılan olarak true değerine ayarlanır. Yedeklemeyi önlemek için considerIp değerini false olarak ayarlayın. |
cellTowers |
array |
Bir dizi baz istasyonu nesnesi. | Aşağıdaki Hücre Kulesi Nesneleri bölümüne bakın. |
wifiAccessPoints |
array |
Bir dizi kablosuz erişim noktası nesnesi. | Aşağıdaki Kablosuz Erişim Noktası Nesneleri bölümüne bakın. |
Örnek bir Coğrafi Konum API'si isteği gövdesi aşağıda gösterilmiştir.
{ "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. ] }
Baz istasyonu nesneleri
İstek gövdesinin cellTowers
dizisi, sıfır veya daha fazla baz istasyonu nesnesi içeriyor.
Alan | JSON türü | Açıklama | Notlar |
---|---|---|---|
cellId |
number (uint32 ) |
Hücrenin benzersiz tanımlayıcısı. | radioType gsm (varsayılan), cdma ,
wcdma ve lte için zorunlu; nr için reddedildi.Aşağıdaki Hücre kimliğini hesaplama bölümüne bakın. Bu bölümde, her radyo türü için geçerli değer aralıkları da listelenmiştir. |
newRadioCellId |
number (uint64 ) |
NR (5G) hücresinin benzersiz tanımlayıcısı. | radioType nr için zorunlu, diğer türler için reddedildi.Aşağıdaki NewRadioCellId'yi hesaplama bölümüne bakın. Bu bölümde, alan için geçerli değer aralığı da listelenir. |
locationAreaCode |
number (uint32 ) |
GSM ve WCDMA ağları için Konum Alan Kodu (LAC). CDMA ağları için Ağ Kimliği (NID). LTE ve NR ağları için İzleme Alanı Kodu (TAC). |
radioType gsm (varsayılan) ve cdma için zorunlu, diğer değerler için isteğe bağlıdır.gsm , cdma , wcdma ve lte ile geçerli aralık: 0-65535.nr ile geçerli aralık: 0-16777215. |
mobileCountryCode |
number (uint32 ) |
Baz kulesinin Mobil Ülke Kodu (MCC). | radioType gsm (varsayılan), wcdma ,
lte ve nr için zorunlu; cdma için kullanılmaz.Geçerli aralık: 0-999. |
mobileNetworkCode |
number (uint32 ) |
Baz kulesinin Mobil Ağ Kodu.
Bu; GSM, WCDMA, LTE ve NR için MNC'dir. CDMA, Sistem kimliğini (SID) kullanır. |
Zorunludur. MNC için geçerli aralık: 0-999. SID için geçerli aralık: 0-32767. |
Aşağıdaki isteğe bağlı alanlar kullanılmaz ancak değerler mevcutsa dahil edilebilir.
Alan | JSON türü | Açıklama | Notlar |
---|---|---|---|
age |
number (uint32 ) |
Bu hücrenin birincil hale gelmesinden bu yana geçen milisaniye sayısı. | Yaş değeri 0 ise cellId veya newRadioCellId mevcut bir ölçümü temsil eder. |
signalStrength |
number (double ) |
dBm olarak ölçülen radyo sinyal gücü. | |
timingAdvance |
number (double ) |
Zamanlama avansı değeri. |
cellId
hesaplanıyor
NR (5G) öncesindeki radyo türleri, ağ hücre kimliğini Geolocation API'ye aktarmak için 32 bit cellId
alanını kullanır.
- GSM (2G) ağları, 16 bit Hücre Kimliği'ni (CID) olduğu gibi kullanır. Geçerli aralık: 0–65535.
- CDMA (2G) ağları, 16 bit Baz İstasyonu Kimliğini (BID) olduğu gibi kullanır. Geçerli aralık: 0-65535.
- WCDMA (3G) ağları, 12 bit Radyo Ağı Denetleyicisi Tanımlayıcısı (RNC-ID) ile 16 bit Hücre Kimliği'ni (CID) birleştiren 28 bitlik bir tam sayı olan UTRAN/GERAN Hücre Kimliği'ni (UC-ID) kullanır.
Formül:rnc_id << 16 | cid
.
Geçerli aralık: 0-268435455.
Not: WCDMA ağlarında yalnızca 16 bitlik Hücre Kimliği değerinin belirtilmesi yanlış veya sıfır sonuçla sonuçlanır. - LTE (4G) ağları, E-UTRAN Hücre Kimliği'ni (ECI) kullanır. Bu, 20 bit E-UTRAN Düğüm B Tanımlayıcısı (eNBId) ile 8 bit Hücre Kimliği'ni (CID) birleştiren 28 bitlik bir tam sayıdır.
Formül:enb_id << 8 | cid
.
Geçerli aralık: 0-268435455.
Not: LTE ağlarında yalnızca 8 bitlik Hücre Kimliği değerinin belirtilmesi yanlış veya sıfır sonuçla sonuçlanır.
API isteğinde bu aralıkların dışına değerlerin yerleştirilmesi, tanımlanmamış davranışa neden olabilir. Google'ın şahsi karar verme yetkisine bağlı olarak API, sayıyı belgelenen aralığa sığdırmak için kesebilir, radioType
için bir düzeltme çıkarabilir veya yanıtta herhangi bir gösterge olmadan bir NOT_FOUND
sonucu döndürebilir.
Aşağıda örnek bir LTE baz istasyonu nesnesi verilmiştir.
{ "cellTowers": [ { "cellId": 170402199, "locationAreaCode": 35632, "mobileCountryCode": 310, "mobileNetworkCode": 410, "age": 0, "signalStrength": -60, "timingAdvance": 15 } ] }
newRadioCellId
hesaplanıyor
Hücre kimlikleri 32 bitten uzun olan yeni ağlar, ağ hücre kimliğini Geolocation API'ye aktarmak için 64 bit newRadioCellId
alanını kullanır.
- NR (5G) ağları, 36 bit Yeni Radyo Hücre Kimliği'ni (NCI) olduğu gibi kullanır.
Geçerli aralık: 0–68719476735.
Aşağıda, bir NR baz istasyonu nesnesi verilmiştir.
{ "cellTowers": [ { "newRadioCellId": 68719476735, "mobileCountryCode": 310, "mobileNetworkCode": 410, "age": 0, "signalStrength": -60, } ] }
Kablosuz erişim noktası nesneleri
İstek gövdesinin wifiAccessPoints
dizisi, iki veya daha fazla kablosuz erişim noktası nesnesi içermelidir. macAddress
zorunludur, diğer tüm alanlar isteğe bağlıdır.
Alan | JSON türü | Açıklama | Notlar |
---|---|---|---|
macAddress |
string |
Kablosuz düğümün MAC adresi. Bu alana genellikle BSS, BSSID veya MAC adresi denir. |
Zorunlu.Kolonla ayrılmış (: ) onaltılık dize.
API üzerinden yalnızca evrensel olarak yönetilen MAC adresleri bulunabilir. Diğer MAC adresleri sessizce bırakılır ve API isteğinin etkin bir şekilde boş kalmasına neden olabilir. Ayrıntılar için İşe yaramayan WiFi erişim noktalarını bırakma konusuna bakın. |
signalStrength |
number (double ) |
dBm olarak ölçülen mevcut sinyal gücü. | Kablosuz erişim noktaları için dBm değerleri genellikle -35 veya daha düşük olup -128 ile -10 dBm arasındadır. Eksi işaretini eklediğinizden emin olun. |
age |
number (uint32 ) |
Bu erişim noktasının algılanmasından bu yana geçen milisaniye sayısı. | |
channel |
number (uint32 ) |
İstemcinin erişim noktasıyla iletişim kurduğu kanal. | |
signalToNoiseRatio |
number (double ) |
dB cinsinden ölçülen mevcut sinyal-gürültü oranı. |
Aşağıda, örnek bir kablosuz erişim noktası nesnesi gösterilmektedir.
{ "macAddress": "f0:d5:bf:fd:12:ae", "signalStrength": -43, "signalToNoiseRatio": 0, "channel": 11, "age": 0 }
Örnek istekler
Geolocation API'yi örnek verilerle denemek isterseniz aşağıdaki JSON dosyasını bir dosyaya kaydedin:
{ "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 } ] }
Ardından komut satırından istekte bulunmak için cURL'yi kullanabilirsiniz:
$ curl -d @your_filename.json -H "Content-Type: application/json" -i "https://www.googleapis.com/geolocation/v1/geolocate?key=YOUR_API_KEY"
Önceki MAC adreslerinin yanıtı aşağıdaki gibi görünür:
{ "location": { "lat": 37.4241173, "lng": -122.0915717 }, "accuracy": 20 }
Kullanılmayan kablosuz erişim noktalarını bırakma
Yerel olarak yönetilen macAddress
içeren kablosuz erişim noktası nesnelerinin kaldırılması, giriş olarak kablosuz ağ kullanan Geolocation API çağrılarının başarı oranını artırabilir.
Filtrelemeden sonra Geolocation API çağrısının başarılı olmayacağı belirlenirse eski konum sinyallerinin veya daha zayıf sinyallere sahip kablosuz erişim noktalarının kullanılması gibi çözümlerden yararlanılabilir. Bu yaklaşım, uygulamanızın konum tahminine olan ihtiyacı ile hassasiyet ve geri çağırma gereksinimleri arasında bir denge oluşturur. Aşağıdaki filtreleme teknikleri, girişlerin nasıl filtreleneceğini gösterir ancak uygulama mühendisi olarak uygulayabileceğiniz çözümleri göstermez.
Yerel olarak yönetilen MAC adresleri, API için kullanışlı konum sinyalleri değildir ve isteklerden sessizce çıkarılır. Bu tür MAC adreslerini kaldırmak için macAddress
'ın en anlamlı ikinci baytının 0
olduğundan emin olun (ör. 02:00:00:00:00:00
içinde 2
ile temsil edilen 1 bit). Yayın MAC adresi (FF:FF:FF:FF:FF:FF
), bu filtrenin hariç tutması yararlı olacak bir MAC adresi örneğidir.
00:00:5E:00:00:00
ile 00:00:5E:FF:FF:FF
arasındaki MAC adresi aralığı IANA için ayrılmıştır ve genellikle ağ yönetimi ve çoklu yayın işlevlerinde kullanılır. Bu da bunların konum sinyali olarak kullanılmasını engeller. Ayrıca bu MAC adreslerini API girişlerinden de kaldırmanız gerekir.
Örneğin, Coğrafi Konum için kullanılabilir MAC adresleri, macs
adlı bir macAddress
dizelerinden toplanabilir:
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');
Bu filtreyi kullandığınızda listede yalnızca 1c:34:56:78:9a:bc
kalır. Bu listede 2'den az kablosuz MAC adresi bulunduğundan istek başarılı olmaz ve bir HTTP 404 (notFound
) yanıtı döndürülür.
Coğrafi konum yanıtları
Başarılı bir coğrafi konum isteği, konum ve yarıçap tanımlayan JSON biçiminde bir yanıt döndürür.
location
: Kullanıcının tahmini enlem ve boylam koordinatları (derece cinsinden). Birlat
ve birlng
alt alanı içerir.accuracy
: Tahmini konumun metre cinsinden doğruluğu. Bu, belirtilenlocation
etrafında bir dairenin yarıçapını gösterir.
{ "location": { "lat": 37.421875199999995, "lng": -122.0851173 }, "accuracy": 120 }