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 eklenen 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 metni

İ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:

Alan JSON türü Açıklama Notlar
homeMobileCountryCode number (uint32) Cihazın ev ağının mobil ülke kodu (MCC). 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ğının Mobil Ağ Kodu. Bu, GSM, WCDMA, LTE ve NR için MNC'dir.
CDMA, Sistem Kimliği'ni (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'dir. Bu alan isteğe bağlı olsa da radyo türü istemci tarafından biliniyorsa her zaman eklenmelidir.
Alan atlanırsa Coğrafi Konum API'si varsayılan olarak gsm değerini kullanır. Bu, varsayılan radyo türü yanlışsa geçersiz veya sıfır sonuç verir.
carrier string Operatörün adı.
considerIp boolean Kablosuz ve baz istasyonu sinyalleri eksikse, boşsa veya cihaz konumunu tahmin etmek için yeterli değilse IP coğrafi konumuna geri dönülüp dönülmeyeceğini belirtir. Varsayılan olarak true değerine ayarlanır. Geri dönüşü önlemek için considerIp değerini false olarak ayarlayın.
cellTowers array Baz istasyonu nesneleri dizisi. Aşağıdaki Baz İstasyonu Nesneleri bölümüne bakın.
wifiAccessPoints array Kablosuz erişim noktası nesneleri dizisi. Aşağıdaki Kablosuz Erişim Noktası Nesneleri bölümüne bakın.

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

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 cellId hesaplama bölümünde, her radyo türü için geçerli değer aralıkları da listelenmektedir.
newRadioCellId number (uint64) NR (5G) hücresinin benzersiz tanımlayıcısı. radioType nr için zorunlu; diğer türler için reddedilir.
Aşağıdaki newRadioCellId değerini hesaplama bölümünde, alan için geçerli değer aralığı da listelenmektedir.
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 istasyonunun mobil ülke kodu (MCC). radioType gsm (varsayılan), wcdma, lte ve nr için zorunludur; cdma için kullanılmaz.
Geçerli aralık: 0-999.
mobileNetworkCode number (uint32) Baz istasyonunun mobil ağ kodu. Bu, GSM, WCDMA, LTE ve NR için MNC'dir.
CDMA, Sistem Kimliği'ni (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 varsa eklenebilir.

Alan JSON türü Açıklama Notlar
age number (uint32) Bu hücrenin birincil olmasından bu yana geçen milisaniye sayısı. Yaş 0 ise cellId veya newRadioCellId mevcut bir ölçümü temsil eder.
signalStrength number (double) dBm cinsinden ölçülen radyo sinyal gücü.
timingAdvance number (double) Zamanlama ilerletme değeri.

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'ni (CID) birleştiren 28 bitlik bir tam sayı değeri 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 Node B tanımlayıcısı (eNBId) ve 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 neden olur.

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ı belgelenen 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ı aşağıdaki gibi 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 aktarmak 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.

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

{
  ...

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

Alan JSON türü Açıklama Notlar
macAddress string Kablosuz ağ düğümünün MAC adresi. Bu genellikle BSS, BSSID veya MAC adresi olarak adlandırılır. Zorunlu. İki nokta ile ayrılmış (:) onaltılık dize.
Yalnızca evrensel olarak yönetilen MAC adresleri API kullanılarak bulunabilir. Diğer MAC adresleri sessizce bırakılır ve API isteğinin etkili bir şekilde boş olmasına neden olabilir. Ayrıntılar için Gereksiz kablosuz erişim noktalarını bırakma başlıklı makaleye bakın.
signalStrength number (double) dBm cinsinden ölçülen mevcut sinyal gücü. Kablosuz erişim noktaları için dBm değerleri genellikle -35 veya daha düşüktür ve -128 ile -10 dBm arasında değişir. Eksi işaretini eklediğinizden emin olun.
-10 dBm'den büyük değerler için API, NOT FOUND değerini döndürür.
age number (uint32) Bu erişim noktası algılandığından beri 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ı.

İ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ı aşağıdaki gibi 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

macAddress olan kablosuz erişim noktası nesnelerini kaldırmak, yerel olarak yönetilen giriş olarak kablosuz kullanan Geolocation API çağrılarının başarı oranını artırabilir. Filtreleme işleminden sonra bir Coğrafi Konum API'si ç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ı 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.

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ı bir macAddress dizisinden toplanabilir:

Java
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")));
Python
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')]
JavaScript
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ğundan 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
}

API, giriş sinyallerine göre bir konum ve doğruluk yarıçapı döndürür. API, yüksek doğrulukta bir konum döndürebilse de doğruluk, mevcut sinyallerin kaynağına, sayısına, yoğunluğuna ve gücüne bağlı olarak değişebilir. Genellikle aşağıdaki doğruluk yarıçaplarını bekleyebilirsiniz:

  • Kablosuz erişim noktaları: İsteğe iki veya daha fazla wifiAccessPoints dahil edilmişse döndürülen doğruluk yarıçapı genellikle 20 metre civarındadır. Doğruluk, erişim noktalarının sayısı ve daha güçlü sinyallerle (dBm cinsinden ölçülür) artar. Sinyal güçleri genellikle -100 ile -20 dBm arasında değişir.
  • Baz istasyonları: Kablosuz bilgisi kullanılamıyorsa veya yetersizse API, konum için cellTowers kullanır. Doğruluk oranı; baz istasyonu türü, sinyal gücü ve ağ yoğunluğuna göre önemli ölçüde değişir:
    • Makro hücreler (en yaygın türdür ve geniş alan kapsamı için kullanılır) daha düşük doğruluk sağlar. Yarıçap genellikle yüzlerce metre aralığında olup baz istasyonu kapsamının seyrek olduğu bölgelerde birkaç bin metreye kadar çıkabilir. Makro hücrelerde 100 metrenin altında bir doğruluk yarıçapı elde etmek nadirdir. Doğruluk, genellikle sinyalleri güçlü olan baz istasyonlarında daha yüksektir. Güçlü sinyaller genellikle LTE için > -110 dBm (sinyal aralığı -140 ila -55 dBm), WCDMA için > -100 dBm (sinyal aralığı -111 ila -53 dBm), CDMA için > -100 dBm (sinyal aralığı -120 ila -40 dBm) ve GSM için > -80 dBm (sinyal aralığı -121 ila -1 dBm) değerindedir.
    • Küçük hücreler (ör. femtocell'ler, picocell'ler veya kapalı alan tekrarlayıcıları), 10-30 metre aralığında doğruluk yarıçaplarıyla en hassas hücre tabanlı konumu sağlar.
  • IP Geolocation: considerIp true ise ve hiçbir kablosuz ya da baz istasyonu sinyali coğrafi olarak konumlandırılamıyorsa API, konumu isteğin IP adresine göre tahmin eder. Bu yöntem, binlerce metreye ulaşabilen yarıçaplarla en düşük doğruluğu sağlar. Doğruluk yarıçapı neden çok büyük? başlıklı makaleyi inceleyin. bölümünde bulabilirsiniz.