Genel Bakış

Giriş

Geolocation API, mobil istemcinin algılayabildiği baz istasyonları ve WiFi düğümleriyle ilgili bilgilere dayalı bir konum ve doğruluk yarıçapı döndürür. Bu dokümanda, bu verileri sunucuya göndermek ve istemciye bir yanıt döndürmek için kullanılan protokol açıklanmaktadır.

İletişim, POST kullanılarak HTTPS üzerinden yapılır. Hem istek hem de yanıt JSON olarak biçimlendirilir ve her ikisinin içerik türü application/json olur.

Başlamadan önce

Geolocation API ile geliştirmeye başlamadan önce kimlik doğrulama koşullarını (API anahtarına ihtiyacınız vardır) ve API kullanımı ve faturalandırması bilgilerini (projenizde faturalandırmayı etkinleştirmeniz gerekir) inceleyin.

Coğrafi konum istekleri

Coğrafi konum istekleri aşağıdaki URL'ye POST kullanılarak gönderilir:

https://www.googleapis.com/geolocation/v1/geolocate?key=YOUR_API_KEY

İsteğinizde, key parametresinin değeri olarak dahil edilecek bir anahtar belirtmelisiniz. key, uygulamanızın API anahtarıdır. Bu anahtar, kota yönetimi için uygulamanızı tanımlar. Anahtar alma hakkında bilgi edinin.

İstek metni

İ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ğı için 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-32.767.
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 eklenmelidir.
Alan çıkarılırsa Geolocation API varsayılan olarak gsm olur. Bu durumda, kabul edilen radyo türünün yanlış olması durumunda geçersiz veya sıfır sonuç olur.
carrier string Kargo şirketi 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 dönülüp sunulmayacağını belirtir. Varsayılan olarak true değerine ayarlanır. Yedeklemeyi devre dışı bırakmak için considerIp öğesini false olarak ayarlayın.
cellTowers array Bir baz istasyonu nesnesi. Aşağıdaki Baz istasyonu 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.

Aşağıda örnek bir Geolocation API isteği gövdesi 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 gereklidir; nr için reddedilmiştir.
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ünü inceleyin.
newRadioCellId number (uint64) NR (5G) hücresinin benzersiz tanımlayıcısı. radioType nr için zorunludur; diğer türler için reddedilmiştir.
Alt alanın geçerli değer aralığını da listeleyen YeniRadioCellId'yi hesaplama bölümüne göz atı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 gereklidir, diğer değerler için isteğe bağlıdır.
gsm, cdma, wcdma ve lte için geçerli aralık: 0-65.535.
nr ile geçerli aralık: 0-16777215.
mobileCountryCode number (uint32) Baz istasyonunun Mobil Ülke Kodu (MM). radioType gsm (varsayılan), wcdma, lte ve nr için gereklidir; 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-32.767.

Aşağıdaki isteğe bağlı alanlar şu anda kullanılmamaktadır ancak değerler varsa eklenebilir.

Alan JSON türü Açıklama Notlar
age number (uint32) Bu hücrenin birincil olduğundan beri geçen milisaniye sayısı. Yaş 0 ise cellId veya newRadioCellId geçerli bir ölçümü temsil eder.
signalStrength number (double) dBm olarak ölçülen radyo sinyali gücü.
timingAdvance number (double) Zamanlamada ilerleme değeri.

cellId hesaplanıyor

NR (5G) öncesi radyo türleri, ağ hücre kimliğini Geolocation API'ye iletmek 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ı, UTRAN/GERAN Hücre Kimliği'ni (UC-ID) kullanır. Bu, 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ğeridir.
    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ç verir.
  • LTE (4G) ağları, E-UTRAN Hücre Kimliğini (ECI) kullanır. E-UTRAN Hücre Kimliği (ECI), 20 bit E-UTRAN Düğüm B Tanımlayıcı'yı (eNBId) ve 8 bit Hücre Kimliğini (CID) birbirine bağlayan 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 bitlik Hücre Kimliği değerinin belirtilmesi yanlış veya sıfır sonuç verir.

API isteği için bu aralıkların dışında değerler yerleştirmek, tanımlanmamış davranışla sonuçlanabilir. Google'ın şahsi karar verme yetkisiyle API, sayıyı kısaltarak belgedeki aralığa sığacak şekilde kısaltabilir, 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 LTE baz istasyonu nesnesi örneği 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 daha yeni ağlar, ağ hücre kimliğini Geolocation API'ye iletmek için 64 bit newRadioCellId alanını kullanır.

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

Aşağıda, NR baz istasyonu ö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 iki veya daha fazla WiFi erişim noktası nesnesi içermelidir. macAddress zorunlu olup 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 alana genellikle BSS, BSSID veya MAC adresi denir. Zorunludur. : (iki nokta) ayrılmış onaltılık dize.
signalStrength number (double) dBm olarak ö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 arasında değişir. Eksi işaretini eklediğinizden emin olun.
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) DB olarak ölçülen mevcut sinyal-gürültü oranı.

Aşağıda örnek bir WiFi erişim noktası nesnesi gösterilmektedir.

{
  "macAddress": "9c:1c:12:b0:45:f1",
  "signalStrength": -43,
  "signalToNoiseRatio": 0,
  "channel": 11,
  "age": 0
}

Coğrafi konum yanıtları

Başarılı bir coğrafi konum isteği, konum ve yarıçapını tanımlayan JSON biçiminde bir yanıt döndürür.

  • location: Kullanıcının tahmini enlem ve boylamını derece cinsinden belirtir. Bir lat ve bir lng alt alanı içerir.
  • accuracy: Tahmini konumun metre cinsinden doğruluğu. Bu, belirli bir location etrafındaki dairenin yarıçapını temsil eder.
{
  "location": {
    "lat": 37.421875199999995,
    "lng": -122.0851173
  },
  "accuracy": 120
}

Hatalar

Bir hata durumunda, standart biçimli bir hata yanıtı gövdesi döndürülür ve HTTP durum kodu bir hata durumuna ayarlanır.

Yanıtta, aşağıdaki anahtarlara sahip tek bir error nesnesine sahip nesne bulunur:

  • code: Bu, yanıtın HTTP durumuyla aynıdır.
  • message: Hatanın kısa bir açıklaması.
  • errors: Oluşan hataların listesi. Her hata, hata türü (reason) ve kısa bir açıklama (message) için bir tanımlayıcı içerir.

Örneğin, geçersiz JSON göndermek şu hatayı döndürür:

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "parseError",
    "message": "Parse Error",
   }
  ],
  "code": 400,
  "message": "Parse Error"
 }
}

Olası hatalar aşağıdakileri içerir:

Neden Alan HTTP Durum Kodu Açıklama
dailyLimitExceeded usageLimits 403 Günlük sınırınızı aştınız.
keyInvalid usageLimits 400 API anahtarınız Geolocation API için geçerli değil. Lütfen anahtarın tamamını eklediğinizden ve API'yi satın aldığınızdan veya kotayı ücretsiz olarak almak için faturalandırmayı etkinleştirdiğinizden ve API'yi etkinleştirdiğinizden emin olun.
userRateLimitExceeded usageLimits 403 Google Cloud Console'da yapılandırdığınız istek sınırını aştınız. Bu sınır genellikle günlük istek, 100 saniyedeki istek ve kullanıcı başına 100 saniye başına istek olarak ayarlanır. Bu sınır, tek bir veya küçük bir kullanıcı grubunun günlük kotanızı tüketmesini önlerken tüm kullanıcılara makul bir erişim sağlamaya engel olacak şekilde yapılandırılmalıdır. Bu sınırları yapılandırmak için API Kullanımını Sınırlama bölümüne bakın.
notFound geolocation 404 İstek geçerliydi ancak sonuç döndürülmedi.
parseError global 400 İstek gövdesi geçerli bir JSON değil. Her bir alanla ilgili ayrıntılar için İstek Gövdesi bölümüne bakın.

Örnek istekler

Geolocation API'yi örnek verilerle denemek isterseniz aşağıdaki JSON'i 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
    }
  ]
}

Ardından, komut satırından istekte bulunmak 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"

Yukarıdaki Mac adreslerinin yanıtı şu şekildedir:

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

(API anahtarınız yoksa API Anahtarı Alma bölümünü inceleyin.)

Ek testler için Android için Yerler SDK'sı ve Android Konum API'leri üzerinden Android cihazınızdan, iOS için Yerler SDK'sı üzerinden iOS cihazınızdan bilgi toplayabilirsiniz.

Sık sorulan sorular

Coğrafi konum yanıtımda neden çok büyük bir accuracy yarıçap alıyorum?

Coğrafi Konum yanıtınız accuracy alanında çok yüksek bir değer gösteriyorsa hizmet, coğrafi konumları WiFi noktaları veya baz istasyonları yerine istek IP'sine göre gösteriyor olabilir. Böyle bir durum, baz istasyonlarının veya erişim noktalarının geçerli ya da tanınmamış olması halinde ortaya çıkabilir.

Sorunun bu olduğunu onaylamak için considerIp özelliğini isteğinizde false olarak ayarlayın. Yanıt bir 404 ise, wifiAccessPoints ve cellTowers nesnelerinizin coğrafi konumunun değiştirilemediğini onaylamış olursunuz.