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 bir anahtar belirtmeniz gerekir. Bu anahtar, key parametresinin değeri olarak eklenir. 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ğı için 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ğı için 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. Bu alan isteğe bağlı olsa da radyo türü istemci tarafından biliniyorsa her zaman dahil edilmelidir.
Bu alan atlanırsa Geolocation API varsayılan olarak gsm değerini kullanır. Bu durumda, varsayılan radyo türü yanlışsa geçersiz sonuçlar veya sıfır sonuç alınır.
carrier string Kargo şirketi adı.
considerIp boolean Kablosuz ve baz istasyonu sinyalleri eksik, boş 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 değer true'dir. Yedeklemeyi ö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 gerekli; nr için reddedildi.
Aşağıdaki cellId hesaplama bölümüne bakın. Bu bölümde, her radyo türü için geçerli değer aralıkları da listelenir.
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 hesaplama bölümüne bakın. Bu bölümde, alan için geçerli değer aralığı da listelenir.
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.		 Zorunlu.
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 mevcutsa dahil edilebilir.

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 ilerlemesi değeri.

cellId hesaplanıyor

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

  • GSM (2G) ağları, 16 bit hücre kimliğini (CID) olduğu gibi kullanır. Geçerli aralık: 0-65535.
  • CDMA (2G) ağları, 16 bit Baz İstasyonu Kimliği'ni (BID) olduğu gibi kullanır. Geçerli aralık: 0-65535.
  • WCDMA (3G) ağları, 12 bitlik Radyo Ağ Denetleyicisi Kimliği (RNC-ID) ile 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 bit hücre kimliği değerinin belirtilmesi, yanlış veya sıfır sonuçlara neden olur.
  • LTE (4G) ağları, 20 bitlik E-UTRAN Düğüm B Tanımlayıcısı (eNBId) ile 8 bitlik Hücre Kimliği'ni (CID) birleştiren 28 bitlik bir tam sayı değeri 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 neden olur.

API isteğinde bu aralıkların dışında değerler kullanılması, tanımlanmamış davranışlara neden olabilir. API, Google'ın takdirine bağlı olarak, sayıyı belgelenen aralığa sığacak şekilde kısaltabilir, 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 bitten uzun olan daha 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 bit Yeni Radyo Hücre Kimliği'ni (NCI) olduğu gibi kullanır.
    Geçerli aralık: 0-68719476735.

İstek gövdesinin 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ğin 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ı yoksayar.

Alan JSON türü Açıklama Notlar
macAddress string Kablosuz düğümünün MAC adresi. Bu genellikle BSS, BSSID veya MAC adresi olarak adlandırılır. Zorunlu. İki nokta üst üste (:) ile ayrılmış onaltılık dize.
API kullanılarak yalnızca evrensel olarak yönetilen MAC adresleri bulunabilir. Diğer MAC adresleri sessizce silinir ve API isteğinin etkili bir şekilde boş olmasına neden olabilir. Ayrıntılı bilgi için Kullanışsız kablosuz erişim noktalarını bırakma başlıklı makaleyi inceleyin.
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.
API, -10 dBm'den büyük değerler için NOT FOUND değerini döndürür.
age number (uint32) Bu erişim noktasının algılanmasından bu yana 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

Geolocation API'yi ö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 aracını 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ı şu şekilde görünür:

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

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

Yayın adresi (FF:FF:FF:FF:FF:FF) olan veya IANA tarafından ayrılmış macAddress'lere sahip 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. Filtreleme işleminden sonra Geolocation API çağrısının başarılı olmayacağı belirlenirse eski konum sinyalleri veya daha zayıf sinyallere sahip kablosuz erişim noktaları kullanma gibi azaltma yöntemleri kullanılabilir. Bu yaklaşım, uygulamanızın konum tahmini ihtiyacı ile kesinlik ve hatırlama gereksinimleri arasında bir denge sağlar. Aşağıdaki filtreleme teknikleri, girişlerin nasıl filtreleneceğini gösterir ancak uygulama mühendisi olarak uygulamayı seçebileceğiniz azaltma yöntemlerini göstermez.

00:00:5E:00:00:00 ile 00:00:5E:FF:FF:FF arasındaki MAC adresleri 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 nedenle, konum sinyali olarak kullanılamazlar. Ayrıca bu MAC adreslerini API'ye girişlerden de kaldırmanız gerekir.

Örneğin, Coğrafi Konum için kullanılabilir MAC adresleri, macs adlı macAddress dize dizisinden toplanabilir:

Java
String[] macs = {"ff:ff:ff:ff:ff:ff", "1c:34:56:78:9a:bc", "00:00:5e:00:00:01"};
ArrayList<String> _macs = new ArrayList<>(Arrays.asList(macs));
_macs.removeIf(m -> !(!m.toUpperCase().equals("FF:FF:FF:FF:FF:FF")
                      && !m.substring(0, 8).toUpperCase().equals("00:00:5E")));
Python
macs = ['ff:ff:ff:ff:ff:ff', '1c:34:56:78:9a:bc', '00:00:5e:00:00:01']
macs = [m for m in macs if (m.upper() != "FF:FF:FF:FF:FF:FF" and m[:8].upper() != '00:00:5E')]
JavaScript
macs = ['ff:ff:ff:ff:ff:ff', '1c:34:56:78:9a:bc', '00:00:5e:00:00:01'];
macs = macs.filter(m => m.toUpperCase() !== "FF:FF:FF:FF:FF:FF"
                        && 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 konumu ve yarıçapı tanımlayan JSON biçimli bir yanıt döndürür.

  • location: Kullanıcının derece cinsinden tahmini enlem ve boylam koordinatları. Bir lat ve bir lng alt alanı içerir.
  • accuracy: Tahmini konumun metre cinsinden doğruluğu. Bu, belirtilen location etrafındaki dairenin yarıçapını temsil eder.
{
  "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ürebilir ancak 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ı: İstek iki veya daha fazla wifiAccessPoints içeriyorsa döndürülen doğruluk yarıçapı genellikle yaklaşık 20 metredir. Doğruluk, erişim noktalarının sayısına ve daha güçlü sinyallere (dBm cinsinden ölçülür) bağlı olarak artar. Sinyal güçleri genellikle -100 ile -20 dBm arasında değişir.
  • Baz istasyonları: Kablosuz ağ bilgileri kullanılamıyorsa veya yetersizse API, konum için cellTowers kullanır. Doğruluk; baz istasyonu türü, sinyal gücü ve ağ yoğunluğuna göre önemli ölçüde değişiklik gösterir:
    • Makro hücreler (en yaygın türdür, geniş alan kapsama için kullanılır) daha düşük doğruluk sağlar. Yarıçap genellikle yüzlerce metre aralığındadır ve baz istasyonu kapsama alanı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 pek mümkün değildir. Doğruluk, genellikle güçlü sinyallere sahip baz istasyonları için 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) şeklindedir.
    • Küçük hücreler (ör. femto hücreler, piko hücreler veya iç mekan tekrarlayıcılar), 10-30 metre aralığında olabilen doğruluk yarıçaplarıyla en hassas hücre tabanlı konumu sağlar.
  • IP Coğrafi Konumu: considerIp, true ise ve hiçbir kablosuz ağ veya baz istasyonu sinyalinin coğrafi konumu belirlenemiyorsa API, isteğin IP adresine göre konumu 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? bölümüne bakın. Sorun Giderme kılavuzuna bakın.