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:

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 durum, varsayılan radyo türü yanlışsa geçersiz veya sıfır sonuç verir.
carrier string Kargo şirketinin 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 WiFi 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": "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.

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üne bakın. Bu bölümde, 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 Calculating newRadioCellId (YeniRadioCellId'yi Hesaplama) bölümüne bakın. Bu bölümde, 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 (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.

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 üst üste ile ayrılmış (:) onaltılık dize.
Yalnızca evrensel olarak yönetilen MAC adresleri API üzerinden 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ı.

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:

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