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 amaçları doğrultusunda uygulamanızı tanımlar. Nasıl anahtar alacağınızı öğrenin.

İstek içeriği

İsteğin gövdesi JSON olarak biçimlendirilmelidir. İsteğin gövdesi eklenmezse sonuçlar, istek konumunun IP adresine göre döndürülür. Aksi belirtilmedikçe aşağıdaki alanlar desteklenir ve 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 (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 edilmelidir. Bu alan atlanırsa Coğrafi Konum API'si varsayılan olarak `gsm` değerine ayarlanır. Bu da, varsayılan radyo türü yanlışsa geçersiz sonuç veya sıfır sonuç olur.
`carrier`	`string`	Kargo şirketinin adı.
`considerIp`	`boolean`	Kablosuz ve baz istasyonu sinyalleri eksikse, boşsa ya da 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`	Baz kulesi 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.

Aşağıda, bir Coğrafi Konum API'si isteğinin gövdesine ilişkin ö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. Aşağıdaki Hücre kimliğini hesaplama bölümünü inceleyin. Bu bölümde, her bir 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. Alan için geçerli değer aralığının da listelendiği aşağıdaki newRadioCellId'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 zorunlu; `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ücre birincil olduğundan beri 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 ilerleme değeri.

`cellId` hesaplanıyor

NR (5G) öncesindeki 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ğini (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ğ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 bit Hücre Kimliği değerinin belirtilmesi yanlış veya sıfır sonuçla sonuçlanır.
LTE (4G) ağları, E-UTRAN Hücre Kimliği'ni (ECI) kullanır. Bu, 20 bit E-UTRAN Düğüm B Tanımlayıcısı (eNBId) ile 8 bit Hücre Kimliğini (CID) birleştiren 28 bitlik bir tam sayı değeridir.
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 yanlış 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 şahsi karar verme yetkisine bağlı olarak sayıyı belgelenen aralığa sığacak şekilde kesebilir, radioType için düzeltme olduğu sonucuna varabilir veya yanıtta herhangi bir gösterge olmadan NOT_FOUND sonucu döndürebilir.

Aşağıda örnek bir LTE baz istasyonu nesnesi verilmiştir.

{
  "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ı, olduğu gibi 36 bit Yeni Radyo Hücre Kimliği'ni (NCI) kullanır.
Geçerli aralık: 0–68719476735.

Aşağıda örnek bir NR baz istasyonu nesnesi verilmiştir.

{
  "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ün MAC adresi. Genellikle BSS, BSSID veya MAC adresi olarak adlandırılır.	Zorunlu.Sütunla ayrılmış (`:`) onaltılık dize. API aracılığıyla, yalnızca evrensel olarak yönetilen MAC adresleri bulunabilir. Diğer MAC adresleri sessizce çıkarılır ve API isteğinin etkili bir şekilde boşalması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üşük olup -128 ile -10 dBm aralığındadır. Eksi işaretini de 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`)	İstemcinin erişim noktasıyla iletişim kurduğu kanal.
`signalToNoiseRatio`	`number` (`double`)	Mevcut sinyal-gürültü oranı dB cinsinden ölçülür.

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 yapmak 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 bağlantıyı kullanan Coğrafi Konum 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ı olamayacağı belirlenirse eski konum sinyallerini veya daha zayıf sinyallere sahip Kablosuz erişim noktalarını kullanmak gibi çözümler kullanılabilir. Bu yaklaşım, uygulamanızın konum tahmini ihtiyacı ile hassasiyet ve geri çağırma gereksinimleri arasında bir denge oluşturur. Aşağıdaki filtreleme teknikleri, girişlerin nasıl filtreleneceğini gösterir ancak uygulama mühendisi olarak uygulayabileceğiniz çözümleri göstermez.

Yerel olarak yönetilen MAC adresleri, API için kullanışlı konum sinyalleri değildir ve isteklerden sessizce çıkarılır. Bu tür MAC adreslerini, macAddress en anlamlı baytının ikinci en küçük bitinin 0 (ör. 02:00:00:00:00:00 içinde 2 ile temsil edilen 1 bit) olmasını sağlayarak kaldırabilirsiniz. Yayın MAC adresi (FF:FF:FF:FF:FF:FF), bu filtre tarafından hariç tutulabilecek 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 konum sinyali olarak kullanılmasını engelleyen ağ yönetimi ve çoklu yayın işlevleri için kullanılır. Bu MAC adreslerini de API girişlerinden kaldırmanız gerekir.

Örneğin, Coğrafi Konum için kullanılabilir MAC adresleri, macs adlı macAddress dizesinden 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 öğe 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, 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 değer, verilen location etrafındaki bir dairenin yarıçapını temsil eder.

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