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

Coğrafi konum istekleri

Coğrafi konum istekleri, aşağıdaki URL'ye POST yöntemi kullanılarak gönderilir:

https://www.googleapis.com/geolocation/v1/geolocate?key=YOUR_API_KEY

İsteğinizde, key parametresinin değeri olarak dahil edilen bir anahtar belirtmeniz gerekir. key, uygulamanızın API anahtarıdır. Bu anahtar, kota yönetimi amacıyla uygulamanızı tanımlar. Anahtar edinmeyi öğrenin.

İstek içeriği

İstek gövdesi 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 Geolocation API istek gövdesi aşağıda gösterilmiştir.

{
  "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.
  ]
}

Baz istasyonu nesneleri

İstek gövdesinin cellTowers dizisi sıfır veya daha fazla baz istasyonu nesnesi içerir.

Aşağıdaki isteğe bağlı alanlar kullanılmaz ancak değerler varsa eklenebilir.

Hesaplanıyor cellId

NR'den (5G) önceki radyo türleri, ağ hücresi kimliğini Geolocation API'ye iletmek için 32 bitlik cellId alanını kullanır.

• GSM (2G) ağları, 16 bitlik hücre kimliğini (CID) olduğu gibi kullanır. Geçerli aralık: 0-65535.
• CDMA (2G) ağları, 16 bitlik Base Station ID'yi (BID) olduğu gibi kullanır. Geçerli aralık: 0-65535.
• WCDMA (3G) ağları, 12 bitlik Radyo Ağı Denetleyici Tanımlayıcısı (RNC-ID) ve 16 bitlik Hücre Kimliği (CID) değerlerini birleştiren 28 bitlik bir tam sayı değeri olan UTRAN/GERAN Hücre Kimliğini (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 Node B tanımlayıcısı (eNBId) ile 8 bitlik hücre kimliğini (CID) birleştiren 28 bitlik bir tam sayı değeri olan E-UTRAN Hücre Kimliğini (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ışında değerler yerleştirmek, tanımlanmamış davranışlara neden olabilir. API, Google'ın takdirine bağlı olarak sayıyı belgelenmiş aralığa sığacak şekilde kesebilir, radioType için bir düzeltme çıkarabilir veya yanıtta herhangi bir gösterge olmadan NOT_FOUND sonucu döndürebilir.

İstek gövdesinin bir parçası olan örnek bir LTE baz istasyonu nesnesi aşağıda verilmiştir.

{
  ...

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

Önceki isteğin yanıtı şu şekilde görünür:

{
  "location": {
    "lat": 37.7801129,
    "lng": -122.4168229
  },
  "accuracy": 180.052
}

Hesaplanıyor newRadioCellId

Hücre kimlikleri 32 bit'ten uzun olan yeni ağlar, ağ hücresi kimliğini Geolocation API'ye iletmek için 64 bit'lik 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.

İstek metninin bir parçası olan bir NR baz istasyonu nesnesi örneğini aşağıda bulabilirsiniz.

{
  ...

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

Önceki isteğe verilen yanıt aşağıdaki gibi görünür:

{
  "location": {
    "lat": 37.7646157,
    "lng": -122.4127361
  },
  "accuracy": 1458.5570522410717
}

Kablosuz erişim noktası nesneleri

İstek gövdesinin wifiAccessPoints dizisi, fiziksel olarak farklı sabit erişim noktası cihazlarını temsil eden iki veya daha fazla kablosuz erişim noktası nesnesi içermelidir. macAddress alanı zorunludur. Diğer tüm alanlar isteğe bağlıdır. Hizmet, uçak ve trenlerdeki gibi hareket eden erişim noktalarını yok sayar.

İstek gövdesinin bir parçası olan örnek bir kablosuz erişim noktası nesnesi aşağıda gösterilmiştir.

{
  ...
  
  "macAddress": "f0:d5:bf:fd:12:ae",
  "signalStrength": -43,
  "signalToNoiseRatio": 0,
  "channel": 11,
  "age": 0
}

Önceki isteğin yanıtı şu şekilde görünür:

{
  "location": {
    "lat": 37.7801129,
    "lng": -122.4168229
  },
  "accuracy": 180.052
}

Örnek istekler

Coğrafi Konum API'sini örnek verilerle denemek istiyorsanız aşağıdaki JSON'u 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 isteğinizi göndermek için curl 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 adresleriyle ilgili yanıt şu şekilde görünür:

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

Kullanılmayan kablosuz erişim noktalarını bırakma

macAddresses olan kablosuz erişim noktası nesnelerini kaldırmak, yerel olarak yönetilen giriş olarak kablosuz bağlantıyı kullanan Geolocation API çağrılarının başarı oranını artırabilir. Filtreleme işleminden sonra bir Geolocation API çağrısının başarılı olamayacağı belirlenirse daha eski konum sinyallerini veya daha zayıf sinyallere sahip kablosuz erişim noktalarını kullanmak gibi azaltma yöntemleri uygulanabilir. Bu yaklaşım, uygulamanızın konum tahmini ihtiyacı ile hassasiyet ve hatırlama gereksinimleri arasında bir denge kurar. Aşağıdaki filtreleme teknikleri, girişlerin nasıl filtreleneceğini gösterir ancak uygulama mühendisi olarak uygulayabileceğiniz azaltma yöntemlerini göstermez.

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ın en anlamlı baytının en az anlamlı ikinci bitinin 0 olmasını sağlayarak kaldırabilirsiniz. Örneğin, 02:00:00:00:00:00 içinde 2 ile gösterilen 1 biti. Yayın MAC adresi (FF:FF:FF:FF:FF:FF), bu filtre tarafından yararlı 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 ile çoklu yayın işlevleri için kullanılır. Bu nedenle, konum sinyali olarak kullanılamazlar. Ayrıca bu MAC adreslerini API'ye girişlerden kaldırmanız gerekir.

Örneğin, coğrafi konum için kullanılabilir MAC adresleri, macs adlı 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 filtre kullanıldığında listede yalnızca 1c:34:56:78:9a:bc kalır. Bu listede 2'den az kablosuz MAC adresi olduğu için istek başarılı olmaz ve 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 konum 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 metre cinsinden doğruluğu. Bu, verilen location etrafındaki dairenin yarıçapını gösterir.

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