Prośby o geolokalizację
Żądania geolokalizacji są wysyłane za pomocą metody POST na ten adres URL:
https://www.googleapis.com/geolocation/v1/geolocate?key=YOUR_API_KEY
W żądaniu musisz podać klucz uwzględniony jako wartość parametru key
. key
to klucz interfejsu API Twojej aplikacji. Ten klucz identyfikuje aplikację na potrzeby zarządzania limitami. Dowiedz się, jak uzyskać klucz.
Treść żądania
Treść żądania musi być w formacie JSON. Jeśli treść żądania nie jest uwzględniona, wyniki są zwracane na podstawie adresu IP lokalizacji żądania. Te pola są obsługiwane, a wszystkie pola są opcjonalne, chyba że określono inaczej:
Pole | Typ JSON | Opis | Notatki |
---|---|---|---|
homeMobileCountryCode |
number (uint32 ) |
Kod kraju mobilnego (MCK) sieci domowej urządzenia. | Obsługiwany przez radioType gsm (domyślnie), wcdma , lte i nr ; nieużywany w cdma .Prawidłowy zakres: 0–999. |
homeMobileNetworkCode |
number (uint32 ) |
Kod sieci komórkowej w sieci domowej urządzenia.
To jest MNC dla GSM, WCDMA, LTE i NR. CDMA używa identyfikatora systemu (SID) |
Prawidłowy zakres dla MNC: 0–999. Prawidłowy zakres dla identyfikatora SID: 0–32767. |
radioType |
string |
Typ nadajnika na telefon komórkowy. Obsługiwane wartości to gsm , cdma , wcdma , lte i nr . |
Chociaż to pole jest opcjonalne, powinno być zawsze uwzględniane, jeśli typ opcji jest znany klientowi. Jeśli pominiesz to pole, interfejs Geolocation API domyślnie ustawi gsm , co poskutkuje nieprawidłowymi lub zerowymi wynikami, jeśli zakładany typ opcji jest nieprawidłowy. |
carrier |
string |
Nazwa przewoźnika. | |
considerIp |
boolean |
Określa, czy w sytuacji, gdy brakuje sygnałów Wi-Fi i stacji bazowych sieci komórkowych, są one puste lub niewystarczające do oszacowania lokalizacji urządzenia. | Domyślna wartość to true . Aby uniknąć działania awaryjnego, ustaw considerIp na false . |
cellTowers |
array |
Tablica obiektów masztów telefonii komórkowej. | Zapoznaj się poniżej z sekcją Obiekty stacji bazowych. |
wifiAccessPoints |
array |
Tablica obiektów punktu dostępu Wi-Fi. | Zapoznaj się z sekcją Obiekty punktu dostępu Wi-Fi poniżej. |
Poniżej znajduje się przykład treści żądania do interfejsu Geolocation API.
{ "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. ] }
Obiekty na stacjach bazowych
Tablica cellTowers
w treści żądania zawiera 0 lub więcej obiektów stacji bazowych.
Pole | Typ JSON | Opis | Notatki |
---|---|---|---|
cellId |
number (uint32 ) |
Unikalny identyfikator komórki. | Wymagany w przypadku zasobów typu radioType gsm (domyślnie), cdma , wcdma i lte . Odrzucono w domenie nr .Zapoznaj się z sekcją Obliczanie identyfikatora komórki poniżej, w której znajdziesz prawidłowe zakresy wartości dla każdego typu opcji. |
newRadioCellId |
number (uint64 ) |
Unikalny identyfikator komórki NR (5G). | Wymagany w przypadku radioType nr ; odrzucony w przypadku innych typów.Zobacz też sekcję Obliczanie newRadioCellId poniżej, która zawiera też prawidłowy zakres wartości dla tego pola. |
locationAreaCode |
number (uint32 ) |
Kod kierunkowy lokalizacji (ang. Location Area Code, LC) w przypadku sieci GSM i WCDMA. Identyfikator sieci (NID) dla sieci CDMA. Kod kierunkowy śledzenia (TAC) dla sieci LTE i NR. |
Wymagany dla radioType gsm (domyślnie) i
cdma . Opcjonalny w przypadku innych wartości.Prawidłowy zakres z wartościami gsm , cdma , wcdma i lte : 0–65535.Prawidłowy zakres z wartością nr : 0–16777215. |
mobileCountryCode |
number (uint32 ) |
Kod kraju sieci komórkowej (MCK) stacji bazowej. | Wymagany w przypadku opcji radioType gsm (domyślnie), wcdma , lte i nr . Nie używany w przypadku cdma .Prawidłowy zakres: 0–999. |
mobileNetworkCode |
number (uint32 ) |
Kod sieci komórkowej stacji bazowej.
To jest MNC dla GSM, WCDMA, LTE i NR. CDMA używa identyfikatora systemu (SID). |
Wymagane. Prawidłowy zakres dla MNC: 0–999. Prawidłowy zakres dla identyfikatora SID: 0–32767. |
Te opcjonalne pola nie są używane, ale mogą być uwzględnione, jeśli wartości są dostępne.
Pole | Typ JSON | Opis | Notatki |
---|---|---|---|
age |
number (uint32 ) |
Liczba milisekund od czasu, gdy ta komórka była główna. | Jeśli wiek wynosi 0, cellId lub newRadioCellId reprezentuje aktualny pomiar. |
signalStrength |
number (double ) |
Siła sygnału radiowego mierzona w dBm. | |
timingAdvance |
number (double ) |
Wartość przebiegu czasu. |
Obliczanie: cellId
Typy opcji przed NR (5G) używają 32-bitowego pola cellId
do przekazywania identyfikatora komórki sieci do interfejsu Geolocation API.
- Sieci GSM (2G) używają 16-bitowego identyfikatora komórkowego (CID) w niezmienionej postaci. Prawidłowy zakres: 0–65 535.
- Sieci CDMA (2G) używają 16-bitowego identyfikatora stacji bazowej (BID). Prawidłowy zakres: 0–65535.
- Sieci WCDMA (3G) używają identyfikatora UTRAN/GERAN Cell Identity (UC-ID), czyli 28-bitowej wartości całkowitej łączącej 12-bitowy identyfikator kontrolera sieci radiowej (RNC-ID) i 16-bitowy identyfikator komórki (CID).
Wzór:rnc_id << 16 | cid
.
Prawidłowy zakres: 0–268435455.
Uwaga: podanie tylko 16-bitowego identyfikatora Cell ID w sieciach WCDMA skutkuje otrzymaniem nieprawidłowych lub zerowego wyniku. - Sieci LTE (4G) korzystają z E-UTRAN Cell Identity (ECI), czyli 28-bitowej wartości całkowitej łączącej 20-bitowy identyfikator węzła E-UTRAN B (eNBId) i 8-bitowy identyfikator komórki (CID).
Wzór:enb_id << 8 | cid
.
Prawidłowy zakres: 0–268435455.
Uwaga: podanie tylko 8-bitowej wartości identyfikatora Cell ID w sieciach LTE skutkuje otrzymaniem nieprawidłowych lub zerowego wyniku.
Znalezienie wartości poza tymi zakresami w żądaniu do interfejsu API może spowodować niezdefiniowane zachowanie. Google według własnego uznania może skrócić liczbę, tak aby mieściła się w udokumentowanym zakresie, wywnioskować poprawkę do radioType
lub zwrócić wynik NOT_FOUND
bez żadnego wskaźnika w odpowiedzi.
Poniżej znajduje się przykładowy obiekt stacji bazowej LTE.
{ "cellTowers": [ { "cellId": 170402199, "locationAreaCode": 35632, "mobileCountryCode": 310, "mobileNetworkCode": 410, "age": 0, "signalStrength": -60, "timingAdvance": 15 } ] }
Obliczam: newRadioCellId
Nowsze sieci, których identyfikatory komórek są dłuższe niż 32 bity, korzystają z 64-bitowego pola newRadioCellId
do przekazywania identyfikatorów komórek sieciowych do interfejsu Geolocation API.
- Sieci NR (5G) używają 36-bitowej tożsamości New Radio Cell Identity (NCI) w niezmienionej postaci.
Prawidłowy zakres: 0–68719476735.
Poniżej znajduje się przykładowy obiekt stacji bazowej sieci komórkowej NR.
{ "cellTowers": [ { "newRadioCellId": 68719476735, "mobileCountryCode": 310, "mobileNetworkCode": 410, "age": 0, "signalStrength": -60, } ] }
Obiekty punktu dostępu Wi-Fi
Tablica wifiAccessPoints
w treści żądania musi zawierać co najmniej 2 obiekty punktu dostępu Wi-Fi. Pole macAddress
jest wymagane. Wszystkie pozostałe pola są opcjonalne.
Pole | Typ JSON | Opis | Notatki |
---|---|---|---|
macAddress |
string |
Adres MAC węzła Wi-Fi. Zwykle jest to adres BSS, BSSID lub MAC. |
Wymagane. Ciąg szesnastkowy rozdzielany kolumnami (: ).
Za pomocą interfejsu API można znajdować tylko uniwersalne adresy MAC. Inne adresy MAC są dyskretnie usuwane, przez co żądanie do interfejsu API może stać się puste. Więcej informacji znajdziesz w sekcji na temat usuwania bezużytecznych punktów dostępu Wi-Fi. |
signalStrength |
number (double ) |
Bieżąca siła sygnału mierzona w dBm. | W przypadku punktów dostępu Wi-Fi wartości dBm wynoszą zwykle -35 lub mniej i wynoszą się od –128 do –10 dBm. Pamiętaj, aby dodać znak minusa. |
age |
number (uint32 ) |
Liczba milisekund od wykrycia tego punktu dostępu. | |
channel |
number (uint32 ) |
Kanał, za pomocą którego klient komunikuje się z punktem dostępu. | |
signalToNoiseRatio |
number (double ) |
Stosunek bieżącego sygnału do szumu, mierzony w dB. |
Poniżej znajduje się przykład obiektu punktu dostępu Wi-Fi.
{ "macAddress": "f0:d5:bf:fd:12:ae", "signalStrength": -43, "signalToNoiseRatio": 0, "channel": 11, "age": 0 }
Przykładowe żądania
Jeśli chcesz wypróbować interfejs Geolocation API z przykładowymi danymi, zapisz następujący kod JSON w pliku:
{ "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 } ] }
Następnie możesz użyć polecenia cURL, aby wysłać żądanie z wiersza poleceń:
$ curl -d @your_filename.json -H "Content-Type: application/json" -i "https://www.googleapis.com/geolocation/v1/geolocate?key=YOUR_API_KEY"
Odpowiedź dla poprzednich adresów MAC wygląda tak:
{ "location": { "lat": 37.4241173, "lng": -122.0915717 }, "accuracy": 20 }
Usuwanie nieużywanych punktów dostępu Wi-Fi
Usunięcie obiektów punktu dostępu Wi-Fi z identyfikatorami macAddress
, które są zarządzane lokalnie, może zwiększyć wskaźnik sukcesu wywołań interfejsu Geolocation API, które jako danych wejściowych używają Wi-Fi.
Jeśli po filtrowaniu można stwierdzić, że wywołanie interfejsu Geolocation API się nie powiedzie, można zastosować środki złagodzające takie jak użycie starszych sygnałów lokalizacyjnych lub punktów dostępowych Wi-Fi ze słabszymi sygnałami. To podejście stanowi kompromis między potrzebą aplikacji dotyczącą szacowania lokalizacji a jej wymaganiami dotyczącymi precyzji i czułości. Poniższe techniki filtrowania pokazują, jak filtrować dane wejściowe, ale nie pokazują środków łagodzących, które może zastosować inżynier aplikacji.
Administrowane lokalnie adresy MAC nie są przydatnymi sygnałami lokalizacji dla interfejsu API i są dyskretnie usuwane z żądań. Możesz usunąć takie adresy MAC, upewniając się, że drugi najmniej istotny bajt z macAddress
to 0
, np. 2
w 02:00:00:00:00:00
. Adres MAC transmisji (FF:FF:FF:FF:FF:FF
) jest przykładem adresu MAC, który można dobrze wykluczyć przez ten filtr.
Zakres adresów MAC od 00:00:5E:00:00:00
do 00:00:5E:FF:FF:FF
jest zarezerwowany dla IANA i często jest używany do zarządzania siecią i funkcji multicast, co wyklucza używanie ich jako sygnału lokalizacji. Musisz też usunąć te adresy MAC z danych wejściowych do interfejsu API.
Na przykład użyteczne adresy MAC do geolokalizacji można zebrać z tablicy ciągów macAddress
o nazwie macs
:
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")));
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')]
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');
Użycie tego filtra sprawi, że na liście pozostanie tylko 1c:34:56:78:9a:bc
. Ta lista zawiera mniej niż 2 adresy MAC Wi-Fi, więc żądanie nie zostanie zrealizowane i zostanie zwrócona odpowiedź HTTP 404 (notFound
).
Odpowiedzi geolokalizacji
Żądanie geolokalizacji zwraca odpowiedź w formacie JSON definiującą lokalizację i promień.
location
: szacowana szerokość i długość geograficzna użytkownika (w stopniach). Zawiera 1 polelat
i 1 pole podrzędnelng
.accuracy
: dokładność szacowanej lokalizacji w metrach. Reprezentuje promień okręgu wokół podanej wartościlocation
.
{ "location": { "lat": 37.421875199999995, "lng": -122.0851173 }, "accuracy": 120 }