Bu sayfa, Cloud Translation API ile çevrilmiştir.

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

İsteğin 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 ana ağının mobil ülke kodu (MM).	`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ü. `gsm`, `cdma`, `wcdma`, `lte` ve `nr` değerleri desteklenir.	Bu alan isteğe bağlı olsa da radyo türü istemci tarafından biliniyorsa her zaman dahil olmalıdır. Alan atlanırsa Coğrafi Konum API'si varsayılan olarak `gsm` değerine ayarlanır. Bu durum, varsayılan radyo türü yanlışsa geçersiz sonuçla veya sıfır sonuçla sonuçlanır.
`carrier`	`string`	Kargo şirketinin adı.
`considerIp`	`boolean`	Kablosuz ağ ve baz istasyonu sinyalleri eksikse, boşsa veya cihaz konumunu tahmin etmek için yeterli değilse IP coğrafi konumuna geri döndürülüp döndürü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.	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.

Aşağıda Coğrafi Konum API'si isteğinin gövde metniyle ilgili örnek gösterilmektedir.

{
  "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 reddedildi. Her bir radyo türü için geçerli değer aralıklarını da listeleyen aşağıdaki Hücre kimliğini hesaplama bölümüne bakın.
`newRadioCellId`	`number` (`uint64`)	NR (5G) hücresinin benzersiz tanımlayıcısı.	`radioType` `nr` için zorunlu; diğer türler için reddedildi. Alan için geçerli değer aralığını da listeleyen aşağıdaki RadioCellId'yi hesaplama bölümüne bakın.
`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ğ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 varsa 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 sinyali gücü.
`timingAdvance`	`number` (`double`)	Zamanlama ilerlemesi değeri.

`cellId` hesaplanıyor

NR (5G) öncesi radyo türleri, ağ hücre kimliğini Geolocation API'ye geçirmek için 32 bit 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 bit Baz İstasyonu 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) ile 16 bit 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çla sonuçlanır.
LTE (4G) ağları, 20 bit E-UTRAN Düğüm Tanımlayıcısı (eNBId) ile 8 bit 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 bit Hücre Kimliği değerinin belirtilmesi hatalı veya sıfır sonuçla sonuçlanır.

API isteğine bu aralıkların dışına değerler yerleştirmek tanımsız davranışa neden olabilir. API, Google'ın takdirine bağlı olarak sayıyı belgelenen aralığa sığacak şekilde kesebilir, radioType için bir düzeltme olduğu sonucuna varabilir veya yanıtta herhangi bir gösterge olmaksızın bir NOT_FOUND sonucu döndürebilir.

Aşağıda örnek bir LTE baz istasyonu nesnesi görebilirsiniz.

{
  "cellTowers": [
    {
      "cellId": 170402199,
      "locationAreaCode": 35632,
      "mobileCountryCode": 310,
      "mobileNetworkCode": 410,
      "age": 0,
      "signalStrength": -60,
      "timingAdvance": 15
    }
  ]
}

`newRadioCellId` hesaplanıyor

Hücre kimlikleri 32 bitten uzun olan yeni ağlar, ağ hücre kimliğini Geolocation API'ye geçirmek için 64 bit newRadioCellId alanını kullanır.

NR (5G) ağları, 36 bit Yeni Radyo Hücresi Kimliği'ni (NCI) olduğu gibi kullanır.
Geçerli aralık: 0–68719476735.

Aşağıda örnek bir NR baz istasyonu nesnesi görebilirsiniz.

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

Kablosuz erişim noktası nesneleri

İstek gövdesinin wifiAccessPoints dizisi, 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 adres genellikle BSS, BSSID veya MAC adresi olarak adlandırılır.	Zorunlu.Kolonla ayrılmış (`:`) onaltılık dize. API aracılığıyla yalnızca evrensel olarak yönetilen MAC adresleri bulunabilir. Diğer MAC adresleri sessizce atılır ve API isteğinin boşalmasıyla sonuçlanabilir. Ayrıntılı bilgi için Kullanışsız Wifi 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üşük olup -128 ile -10 dBm aralığındadır. Eksi işaretini eklemeyi unutmayın.
`age`	`number` (`uint32`)	Bu erişim noktasının algılanmasından bu yana geçen milisaniye sayısı.
`channel`	`number` (`uint32`)	Müşterinin 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": "9c:1c:12:b0:45:f1",
  "signalStrength": -43,
  "signalToNoiseRatio": 0,
  "channel": 11,
  "age": 0
}

Örnek istekler

Geolocation API'yi örnek verilerle denemek istiyorsanız aşağıdaki JSON dosyasını bir dosyaya kaydedin:

{
  "considerIp": "false",
  "wifiAccessPoints": [
    {
      "macAddress": "3c:37:86:5d:75:d4",
      "signalStrength": -35,
      "signalToNoiseRatio": 0
    },
    {
      "macAddress": "94:b4:0f:fd:c1:40",
      "signalStrength": -35,
      "signalToNoiseRatio": 0
    }
  ]
}

Daha sonra komut satırından isteğinizi iletmek 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 adresleri için yanıt şu şekildedir:

{
  "location": {
      "lat": 37.4241876,
      "lng": -122.0917381
  },
  "accuracy": 32.839
}

Kullanılmayan kablosuz erişim noktaları kaldırılıyor

Yerel olarak yönetilen macAddress'lere sahip kablosuz erişim noktası nesnelerinin kaldırılması, giriş olarak kablosuz ağı kullanan Geolocation API çağrılarının başarı oranını artırabilir. Filtrelemeden sonra bir Coğrafi Konum API çağrısının başarılı olmayacağı belirlenirse eski konum sinyallerini veya daha zayıf sinyallere sahip kablosuz erişim noktalarını kullanmak gibi azaltma yöntemleri kullanılabilir. Bu yaklaşım, uygulamanızın konum tahmini ihtiyacı ile hassasiyet ve geri çağırma gereksinimleri arasında denge sağlar. Aşağıdaki filtreleme teknikleri, girişlerin nasıl filtreleneceğini gösterir ancak uygulama mühendisi olarak uygulayabileceğiniz azaltmaları göstermez.

Yerel olarak yönetilen MAC adresleri, API için kullanışlı konum sinyalleri değildir ve sessizce isteklerden çıkarılır. macAddress ürününün en anlamlı baytının ikinci en az anlamlı bitinin 0 (ör. 02:00:00:00:00:00 öğesinde 2 ile temsil edilen 1 bit) olduğundan emin olarak bu tür MAC adreslerini kaldırabilirsiniz. Yayın MAC adresi (FF:FF:FF:FF:FF:FF), bu filtre tarafından faydalı olabilecek bir MAC adresi örneğidir.

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 konum sinyali olarak kullanılmasını engelleyen çok noktaya 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ılabilir 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 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, konum 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 değer, belirtilen location etrafında bir dairenin yarıçapını temsil eder.

{
  "location": {
    "lat": 37.421875199999995,
    "lng": -122.0851173
  },
  "accuracy": 120
}