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ść
key
. key
to identyfikator Twojej aplikacji
klucz interfejsu API. Ten klucz identyfikuje aplikację na potrzeby limitów
i zarządzania nimi. Dowiedz się, jak uzyskać klucz.
Treść żądania
Treść żądania musi być w formacie JSON. Jeśli nie podasz treści żądania, wyniki są zwracane na podstawie adresu IP lokalizacji żądania. Wymienione niżej pola to obsługiwane i wszystkie pola są opcjonalne, o ile nie określono inaczej:
Pole | Typ JSON | Opis | Uwagi |
---|---|---|---|
homeMobileCountryCode |
number (uint32 ) |
Kod kraju mobilnego (MCK) sieci domowej urządzenia. | Obsługiwany w przypadku radioType gsm (domyślnie),
wcdma , lte i nr ; nieużywane w przypadku cdma .Prawidłowy zakres: 0–999. |
homeMobileNetworkCode |
number (uint32 ) |
Kod sieci komórkowej w sieci domowej urządzenia.
To MNC dla GSM, WCDMA, LTE i NR. CDMA używa identyfikatora systemu (SID) |
Prawidłowy zakres dla MNC: 0–999. Prawidłowy zakres dla SID: 0–32767. |
radioType |
string |
Typ nadajnika na telefon komórkowy. Obsługiwane wartości to gsm , cdma ,
wcdma , lte i nr . |
To pole jest opcjonalne, ale powinno być zawsze uwzględniane, jeśli typ opcji to
znane klientowi. Jeśli to pole zostanie pominięte, interfejs Geolocation API domyślnie ustawi wartość gsm ,
co zwraca wyniki nieprawidłowe lub zerowe, jeśli zakładany typ opcji to
niepoprawnie. |
carrier |
string |
Nazwa przewoźnika. | |
considerIp |
boolean |
Określa, czy w razie braku sygnałów Wi-Fi i stacji bazowych sieci komórkowych stosować geolokalizację IP. jest puste lub niewystarczające do oszacowania lokalizacji urządzenia. | Domyślna wartość to true . Ustaw considerIp na
false , aby zapobiec działaniu awaryjnego. |
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. | Zobacz 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
obiektach nadajników telefonii komórkowej.
Pole | Typ JSON | Opis | Uwagi |
---|---|---|---|
cellId |
number (uint32 ) |
Unikalny identyfikator komórki. | Wymagany w przypadku aplikacji radioType gsm (domyślnie), cdma ,
wcdma i lte ; odrzucone dla nr .Przeczytaj sekcję Obliczanie identyfikatora komórki poniżej, która zawiera też listę prawidłowe zakresy wartości dla każdego typu opcji. |
newRadioCellId |
number (uint64 ) |
Unikalny identyfikator komórki NR (5G). | Wymagany w przypadku aplikacji radioType nr ; odrzucone dla innego
.Przeczytaj sekcję Obliczanie newRadioCellId poniżej. , który 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 obszaru śledzenia (TAC) w sieciach LTE i NR. |
Wymagany w przypadku aplikacji 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 aplikacji radioType gsm (domyślnie), wcdma ,
lte i nr ; nieużywane w przypadku cdma .Prawidłowy zakres: 0–999. |
mobileNetworkCode |
number (uint32 ) |
Kod sieci komórkowej stacji bazowej.
To 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 SID: 0–32767. |
Te opcjonalne pola nie są używane, ale mogą być uwzględnione, jeśli i dostępności informacji.
Pole | Typ JSON | Opis | Uwagi |
---|---|---|---|
age |
number (uint32 ) |
Liczba milisekund od czasu, gdy ta komórka była główna. | Jeśli wiek to 0, cellId lub newRadioCellId oznacza aktualną wartość
pomiar skuteczności. |
signalStrength |
number (double ) |
Siła sygnału radiowego mierzona w dBm. | |
timingAdvance |
number (double ) |
przedział czasu . |
Obliczanie: cellId
Typy radiowe przed NR (5G) używają 32-bitowego pola cellId
do przekazywania sieci
identyfikator komórki 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–65 535.
- Sieci WCDMA (3G) używają identyfikatora UTRAN/GERAN Cell Identity (UC-ID), który jest 28-bitową liczbą całkowitą.
wartość stanowiąca połączenie 12-bitowego identyfikatora kontrolera sieci radiowej (RNC-ID) i 16-bitowego identyfikatora
Identyfikator sieci komórkowej (ID klienta).
Wzór:rnc_id << 16 | cid
.
Prawidłowy zakres: 0–268435455.
Uwaga: określenie tylko 16-bitowej wartości identyfikatora Cell ID w sieciach WCDMA powoduje nieprawidłowych lub nieprawidłowych wyników. - Sieci LTE (4G) korzystają z protokołu E-UTRAN Cell Identity (ECI), czyli 28-bitowej liczby całkowitej.
połączenie 20-bitowego identyfikatora węzła E-UTRAN B (eNBId) i 8-bitowego identyfikatora komórki (CID).
Wzór:enb_id << 8 | cid
.
Prawidłowy zakres: 0–268435455.
Uwaga: określenie tylko 8-bitowej wartości identyfikatora Cell ID w sieciach LTE powoduje nieprawidłowych lub nieprawidłowych wyników.
Znalezienie wartości poza tymi zakresami w żądaniu do interfejsu API może spowodować niezdefiniowane zachowanie. Interfejs API
Google może według własnego uznania skrócić liczbę, tak aby mieściła się w udokumentowanym zakresie, co pozwoli uzyskać
poprawkę do radioType
lub zwróć wynik NOT_FOUND
bez żadnych
wskaźnik
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-bitowe, korzystają z 64-bitowego kodu
Pole newRadioCellId
do przekazywania identyfikatora komórki sieciowej do
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ć dwa
lub więcej obiektów punktu dostępu Wi-Fi. Pole macAddress
jest wymagane; wszystkie
a inne pola są opcjonalne.
Pole | Typ JSON | Opis | Uwagi |
---|---|---|---|
macAddress |
string |
Adres MAC węzła Wi-Fi. Zwykle jest to adres BSS, BSSID lub MAC. |
Wymagane. Ciąg szesnastkowy rozdzielany kolumnami (: ).
Tylko dostępne powszechnie Adresy MAC można znajdować za pomocą interfejsu API. Inne adresy MAC dyskretnie pominięte i może doprowadzić do tego, że żądanie API puste. Szczegółowe informacje znajdziesz w sekcji Rezygnacja z bezużytecznego dostępu do Wi-Fi punktów. |
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ładem zapisz w pliku następujący kod JSON:
{ "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ć cURL, aby wpisz polecenie w wierszu 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
Usuwanie obiektów punktu dostępu Wi-Fi, które macAddress
są
lokalnie administrowane
może zwiększyć wskaźnik sukcesu wywołań interfejsu API geolokalizacji, które używają Wi-Fi jako danych wejściowych.
Jeśli po filtrowaniu można określić, że wywołanie interfejsu Geolocation API
nie uda się rozwiązać problemu, wykorzystując np. starsze sygnały lokalizacyjne lub punkty dostępu Wi-Fi
można wykorzystać słabsze sygnały. To podejście stanowi kompromis
potrzeby aplikacji szacowania lokalizacji oraz jej dokładności i czułości
. Poniższe techniki filtrowania pokazują, jak filtrować
danych wejściowych, ale nie pokazuje środków zaradczych, które można zastosować.
inżyniera, wybierz się do programu.
Lokalnie administrowane adresy MAC nie są przydatnymi sygnałami lokalizacji dla:
API i są dyskretnie pomijane w żądaniach. Możesz usunąć takie adresy MAC
upewniając się, że drugi najmniej istotny element
Najważniejszy bajt elementu macAddress
to 0
, np.
2
w argumencie
02:00:00:00:00:00
. Adres MAC transmisji
(FF:FF:FF:FF:FF:FF
) to przykładowy adres MAC,
co można by wykluczyć przez ten filtr.
Zakres adresów MAC z zakresu od 00:00:5E:00:00:00
do
00:00:5E:FF:FF:FF
to
zarezerwowany
dla IANA i często używany do zarządzania siecią i funkcji multicast.
co wyklucza używanie ich jako sygnału lokalizacyjnego. Usuń te elementy
Adresy MAC z danych wejściowych do interfejsu API.
Na przykład adresy MAC używane do geolokalizacji można zebrać z
tablica macAddress
ciągów 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 powoduje wyświetlenie tylko 1c:34:56:78:9a:bc
. Ponieważ ta lista zawiera
mniej niż 2 adresy MAC sieci Wi-Fi,
żądanie nie powiedzie się i zostanie wyświetlony kod HTTP 404
(notFound
)
odpowiedź.
Odpowiedzi geolokalizacji
Żądanie geolokalizacji zwraca odpowiedź w formacie JSON który określa lokalizację i promień.
location
: szacowana szerokość i długość geograficzna użytkownika. współrzędne w stopniach. Zawiera 1 elementlat
i 1lng
.accuracy
: dokładność szacowanej lokalizacji w m Reprezentuje promień okręgu wokół podanegolocation
{ "location": { "lat": 37.421875199999995, "lng": -122.0851173 }, "accuracy": 120 }