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

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:

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

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). Bir lat ve bir lng alt alanı içerir.
• accuracy: Tahmini konumun metre cinsinden doğruluğu. Bu, belirtilen location etrafında bir dairenin yarıçapını gösterir.

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