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. Birlat
ve birlng
alt alanı içerir.accuracy
: Tahmini konumun metre cinsinden doğruluğu. Bu, belirli birlocation
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.