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, 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

İstek metni 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ğini (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 eklenmelidir.
Alan atlanırsa Coğrafi Konum API'si varsayılan olarak gsm değerini alır. Bu durumda, varsayılan radyo türü yanlışsa geçersiz veya sıfır sonuç elde edilir.
carrier string Kargo şirketinin adı.
considerIp boolean Kablosuz ağ ve baz istasyonu sinyalleri eksik, boş veya cihaz konumunu tahmin etmek için yeterli değilse IP coğrafi konumuna dönülüp dönülmeyeceğini belirtir. Varsayılan olarak true değerine ayarlanır. Yedeklemeyi önlemek için considerIp değerini false olarak ayarlayın.
cellTowers array Bir dizi baz istasyonu nesnesi. Aşağıdaki Cep Kulesi Nesneleri bölümüne bakın.
wifiAccessPoints array WiFi erişim noktası nesneleri dizisi. Aşağıdaki Kablosuz Ağ Erişim Noktası Nesneleri bölümüne bakın.

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

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 reddedilir.
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 reddedildi.
Aşağıdaki newRadioCellId değerini hesaplama bölümüne bakın. Bu bölümde, alanın 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 zorunludur, 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 kulesinin Mobil Ağ Kodu. Bu, GSM, WCDMA, LTE ve NR için MNC'dir.
CDMA, sistem kimliğini (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 mevcutsa dahil edilebilir.

Alan JSON türü Açıklama Notlar
age number (uint32) Bu hücrenin birincil olduğu andan itibaren 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 ilerleme değeri.

cellId hesaplanıyor

NR'den (5G) önceki radyo türleri, ağ hücre kimliğini Geolocation API'ye iletmek için 32 bitlik 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 bitlik baz istasyonu 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çlara yol açar.
  • LTE (4G) ağları, 20 bitlik E-UTRAN B Noktası Tanımlayıcısı (eNBId) ile 8 bitlik Hücre Kimliği'ni (CID) birleştiren 28 bitlik bir tam sayı 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 yol açar.

API isteğine bu aralıkların dışındaki değerleri yerleştirmek, tanımlanmamış davranışlara neden olabilir. Google'ın şahsi karar verme yetkisiyle API, sayıyı belgelenen aralığa sığdırmak için kesebilir, radioType için bir düzeltme sonucu çıkarabilir veya yanıtta herhangi bir gösterge olmaksızın 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
    }
  ]
}

Hesaplama newRadioCellId

Hücre kimlikleri 32 bitten uzun olan 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 bitlik yeni radyo hücre kimliğini (NCI) olduğu gibi kullanır.
    Geçerli aralık: 0-68719476735.

Aşağıda bir NR hücre kulesi nesnesi örneği verilmiştir.

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

WiFi 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. macAddress zorunludur; diğer tüm alanlar isteğe bağlıdır.

Alan JSON türü Açıklama Notlar
macAddress string Kablosuz düğümün MAC adresi. Bu genellikle BSS, BSSID veya MAC adresi olarak adlandırılır. Zorunlu. İki nokta işaretiyle ayrılmış (:) onaltılık dize.
API üzerinden yalnızca evrensel olarak yönetilen MAC adresleri bulunabilir. Diğer MAC adresleri sessizce atlanır ve API isteğinin etkili bir şekilde boş olmasına yol açabilir. Ayrıntılı bilgi için Yersiz kablosuz erişim noktalarını kaldırma başlıklı makaleyi inceleyin.
signalStrength number (double) dBm olarak ölçülen mevcut sinyal gücü. Kablosuz erişim noktalarında 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.
age number (uint32) Bu erişim noktasının algılandığı andan itibaren 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ı.

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 verileriyle denemek istiyorsanız aşağıdaki JSON dosyasını 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 yapmak 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 adreslerine verilen yanıt şöyle görünür:

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

Kullanılmayan WiFi erişim noktalarını kaldırma

Yerel olarak yönetilen macAddress'ler içeren kablosuz erişim noktası nesnelerini kaldırmak, giriş olarak kablosuz bağlantı kullanan Geolocation API çağrılarının başarı oranını artırabilir. Filtreleme yapıldıktan sonra bir Coğrafi Konum API çağrısının başarılı olmayacağı belirlenebilirse eski konum sinyalleri veya daha zayıf sinyallere sahip kablosuz AP'ler kullanma gibi azaltıcı önlemler kullanılabilir. Bu yaklaşım, uygulamanızın konum tahmini ihtiyacı ile doğruluk ve geri çağırma gereksinimleri arasında bir denge kurar. Aşağıdaki filtreleme tekniklerinde girişlerin nasıl filtreleneceği gösterilmektedir ancak uygulama mühendisi olarak uygulamayı seçebileceğiniz azaltma yöntemleri gösterilmemektedir.

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 en önemli baytının ikinci en az önemli bitinin 0 olduğundan emin olarak kaldırabilirsiniz (ör. 02:00:00:00:00:00'deki 2 ile temsil edilen 1 bit). Yayın MAC adresi (FF:FF:FF:FF:FF:FF), bu filtre tarafından faydalı 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 ve çoklu yayın işlevleri için kullanılır. Bu da konum sinyali olarak kullanılmalarını engeller. Bu MAC adreslerini API'ye gelen girişlerden de kaldırmanız gerekir.

Örneğin, coğrafi konum için kullanılabilen MAC adresleri, macs adlı bir macAddress dizesi 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 filtrenin kullanılması sonucunda listede yalnızca 1c:34:56:78:9a:bc öğe 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, bir konumu 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, belirli bir location etrafındaki dairenin yarıçapını temsil eder.
{
  "location": {
    "lat": 37.421875199999995,
    "lng": -122.0851173
  },
  "accuracy": 120
}