Coğrafi konum isteği ve yanıtı

Coğrafi konum istekleri

Coğrafi konum istekleri, POST kullanılarak aşağıdaki URL'ye 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

İstek metni JSON olarak biçimlendirilmelidir. İstek 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:

Ö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.

Aşağıdaki isteğe bağlı alanlar kullanılmaz ancak değerler mevcutsa dahil edilebilir.

cellId hesaplanıyor

NR'den (5G) önceki radyo türleri, ağ hücre kimliğini Geolocation API'ye iletmek için 32 bitlik 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 bitlik baz istasyonu 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çlara yol açar.
• LTE (4G) ağları, 20 bitlik E-UTRAN B Noktası Tanımlayıcısı (eNBId) ile 8 bitlik Hücre Kimliği'ni (CID) birleştiren 28 bitlik bir tam sayı olan E-UTRAN Hücre Kimliği'ni (ECI) kullanı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çlara yol açar.

API isteğine bu aralıkların dışındaki değerleri yerleştirmek, tanımlanmamış davranışlara neden olabilir. Google'ın şahsi karar verme yetkisiyle API, sayıyı belgelenen aralığa sığdırmak için kesebilir, radioType için bir düzeltme sonucu çıkarabilir veya yanıtta herhangi bir gösterge olmaksızın NOT_FOUND sonucu döndürebilir.

Aşağıda bir LTE baz istasyonu nesnesi örneği verilmiştir.

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

Hesaplama newRadioCellId

Hücre kimlikleri 32 bitten uzun olan yeni ağlar, ağ hücre kimliğini Geolocation API'ye iletmek için 64 bitlik newRadioCellId alanını kullanır.

• NR (5G) ağları, 36 bitlik yeni radyo hücre kimliğini (NCI) olduğu gibi kullanır.
  Geçerli aralık: 0-68719476735.

Aşağıda bir NR hücre kulesi nesnesi örneği verilmiştir.

{
  "cellTowers": [
    {
      "newRadioCellId": 68719476735,
      "mobileCountryCode": 310,
      "mobileNetworkCode": 410,
      "age": 0,
      "signalStrength": -60,
    }
  ]
}

WiFi erişim noktası nesneleri

İstek metninin wifiAccessPoints dizisi, fiziksel olarak farklı erişim noktası cihazlarını temsil eden iki veya daha fazla kablosuz erişim noktası nesnesi içermelidir. macAddress zorunludur; diğer tüm alanlar isteğe bağlıdır.

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

Coğrafi Konum API'sini örnek verileriyle denemek istiyorsanız aşağıdaki JSON dosyasını 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 isteğinizi yapmak 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 adreslerine verilen yanıt şöyle görünür:

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

Kullanılmayan WiFi erişim noktalarını kaldırma

Yerel olarak yönetilen macAddress'ler içeren kablosuz erişim noktası nesnelerini kaldırmak, giriş olarak kablosuz bağlantı kullanan Geolocation API çağrılarının başarı oranını artırabilir. Filtreleme yapıldıktan sonra bir Coğrafi Konum API çağrısının başarılı olmayacağı belirlenebilirse eski konum sinyalleri veya daha zayıf sinyallere sahip kablosuz AP'ler kullanma gibi azaltıcı önlemler kullanılabilir. Bu yaklaşım, uygulamanızın konum tahmini ihtiyacı ile doğruluk ve geri çağırma gereksinimleri arasında bir denge kurar. Aşağıdaki filtreleme tekniklerinde girişlerin nasıl filtreleneceği gösterilmektedir ancak uygulama mühendisi olarak uygulamayı seçebileceğiniz azaltma yöntemleri gösterilmemektedir.

Yerel olarak yönetilen MAC adresleri, API için yararlı konum sinyalleri değildir ve isteklerden sessizce çıkarılır. Bu tür MAC adreslerini, macAddress'ün en önemli baytının ikinci en az önemli bitinin 0 olduğundan emin olarak kaldırabilirsiniz (ör. 02:00:00:00:00:00'deki 2 ile temsil edilen 1 bit). Yayın MAC adresi (FF:FF:FF:FF:FF:FF), bu filtre tarafından faydalı bir şekilde hariç tutulacak 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şlevleri için kullanılır. Bu da konum sinyali olarak kullanılmalarını engeller. Bu MAC adreslerini API'ye gelen girişlerden de kaldırmanız gerekir.

Örneğin, coğrafi konum için kullanılabilen MAC adresleri, macs adlı bir macAddress dizesi dizisinden 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 filtrenin kullanılması sonucunda listede yalnızca 1c:34:56:78:9a:bc öğe 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, bir konumu ve yarıçapı tanımlayan JSON biçimli bir yanıt döndürür.

• location: Kullanıcının tahmini enlem ve boylam koordinatları (derece cinsinden). Bir lat ve bir lng alt alanı içerir.
• accuracy: Tahmini konumun doğruluğu (metre cinsinden). Bu, belirli bir location etrafındaki dairenin yarıçapını temsil eder.

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