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 dahil edilecek bir anahtar belirtmeniz gerekir. key, uygulamanızın API anahtarıdır. Bu anahtar, kota yönetimi amacıyla uygulamanızı tanımlar. Anahtar edinme hakkında bilgi edinin.

İstek içeriği

İstek gövdesi JSON biçiminde olmalıdır. İ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 ana 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 Operatör 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. Yedek ayarını ö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ı nesnesi dizisi. Aşağıdaki Kablosuz Bağlantı Noktası Nesneleri bölümüne bakın.

Coğrafi Konum API'si istek gövdesinin örneği 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.
  ]
}

Gsm kulesi 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 zorunludur; 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 zorunludur; diğer türler için reddedilir.
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 izleme 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) Hücre kulesinin 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) Hücresel kulenin 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 Coğrafi Konum 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 istasyonu kimliğini (BID) olduğu gibi kullanır. Geçerli aralık: 0-65535.
  • WCDMA (3G) ağları, 12 bit radyo ağı denetleyici tanımlayıcısı (RNC-ID) ve 16 bit hücre kimliğini (CID) birleştiren 28 bitlik bir tam sayı 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 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ç verir.

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 yapabilir veya yanıtta herhangi bir gösterge olmadan bir NOT_FOUND sonucu döndürebilir.

Aşağıda bir LTE hücre kulesi 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 bitten uzun olan daha yeni ağlar, ağ hücre kimliğini Coğrafi Konum 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 gövdesinin 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. Genellikle BSS, BSSID veya MAC adresi olarak adlandırılır. Zorunlu. İki nokta işaretiyle ayrılmış (:) on altılık dize.
API üzerinden yalnızca evrensel olarak yönetilen MAC adresleri bulunabilir. Diğer MAC adresleri sessizce atılır ve API isteğinin etkili bir şekilde boş olmasına yol açabilir. Ayrıntılar için Kullanılmayan kablosuz erişim noktalarını kaldırma başlıklı makaleyi inceleyin.
signalStrength number (double) dBm cinsinden ö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ılanmasından sonraki 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'yi ö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, isteğinizi komut satırından 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 şu şekilde 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 ağı kullanan Coğrafi Konum 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 getirme gereksinimleri arasında bir denge kurar. Aşağıdaki filtreleme teknikleri, girişlerin nasıl filtreleneceğini gösterir ancak uygulama mühendisi olarak uygulamayı tercih edebileceğ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 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 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 konum sinyali olarak kullanılmasını engelleyen ağ yönetimi ve çoklu yayın işlevleri için kullanılır. Bu MAC adreslerini API'ye yapılan girişlerden de kaldırmanız gerekir.

Örneğin, coğrafi konum için kullanılabilen MAC adresleri, macs adlı bir macAddress dize 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 yer alır. Bu listede 2'den az kablosuz MAC adresi bulunduğ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 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
}