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. Nasıl anahtar alacağınızı öğ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": "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ç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 (BID) değerini 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.

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
    }
  ]
}

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.

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

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

Kablosuz 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. Vesikalık fotoğraf 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 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, giriş olarak kablosuz bağlantıyı kullanan Geolocation API çağrılarının başarı oranını artırabilir. Filtrelemeden sonra bir Coğrafi Konum API'si çağrısının başarılı olamayacağı belirlenirse eski konum sinyallerini veya daha zayıf sinyallere sahip kablosuz erişim noktalarını kullanma 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.

Stones API için yerel olarak yönetilen MAC adresleri 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 bit. 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 doğruluğu (metre cinsinden). Bu, verilen location etrafındaki dairenin yarıçapını gösterir.

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