Prośba o geolokalizację i odpowiedź

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, który będzie widoczny 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ć sformatowana w formacie JSON. Jeśli treść żądania nie jest uwzględniona, wyniki są zwracane na podstawie adresu IP lokalizacji żądania. Obsługiwane są poniższe pola, a wszystkie pola są opcjonalne, chyba że zaznaczono inaczej:

Pole Typ JSON Opis Uwagi
homeMobileCountryCode number (uint32) Kod kraju mobilnego (MCK) sieci domowej urządzenia. Obsługiwane przez: radioType gsm (domyślnie), wcdma, lte i nr; nieużywane w cdma.
Prawidłowy zakres: 0–999.
homeMobileNetworkCode number (uint32) Kod sieci komórkowej domowej na urządzeniu. 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 radiowego urządzenia mobilnego. Obsługiwane wartości to gsm, cdma, wcdma, lte i nr. To pole jest opcjonalne, ale powinno być zawsze uwzględniane, jeśli klient rozpoznaje typ radiowy.
Jeśli to pole zostanie pominięte, interfejs Geolocation API przyjmuje domyślnie wartość gsm, co spowoduje nieprawidłowe wyniki lub zerową liczbę wyników w przypadku założenia nieprawidłowego typu radiowego.
carrier string Nazwa przewoźnika.
considerIp boolean Określa, czy wrócić do geolokalizacji na podstawie IP, jeśli brakuje sygnałów Wi-Fi i stacji bazowych sieci komórkowej, jest ona pusta lub jest niewystarczająca do oszacowania lokalizacji urządzenia. Domyślna wartość to true. Aby zapobiec kreacji zastępczej, ustaw considerIp na false.
cellTowers array Zbiór obiektów nadajników telefonii komórkowej. Zobacz sekcję Obiekty stacji bazowej poniżej.
wifiAccessPoints array Tablica obiektów punktu dostępu Wi-Fi. Przeczytaj sekcję Obiekty punktu dostępu Wi-Fi poniżej.

Poniżej znajdziesz przykładową treść żą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 stacji bazowych

Tablica cellTowers w treści żądania zawiera co najmniej 0 obiektów masztów telefonii komórkowej.

Pole Typ JSON Opis Uwagi
cellId number (uint32) Unikalny identyfikator komórki. Wymagany dla: radioType gsm (domyślny), cdma, wcdma i lte; odrzucony dla: nr.
W sekcji Obliczanie identyfikatora komórki poniżej znajdziesz też listę prawidłowych zakresów wartości dla poszczególnych rodzajów opcji.
newRadioCellId number (uint64) Unikalny identyfikator komórki NR (5G). Wymagany dla: radioType nr; odrzucony w przypadku innych typów.
Zapoznaj się poniżej z sekcją Obliczanie parametru newRadioCellId, która zawiera też prawidłowy zakres wartości pola.
locationAreaCode number (uint32) Kod lokalizacji (LAC) dla sieci GSM i WCDMA.
Identyfikator sieci (NID) dla sieci CDMA.
Kod obszaru śledzenia (TAC) w sieciach LTE i NR.		 Wymagany dla radioType gsm (domyślny) i cdma; opcjonalny w przypadku innych wartości.
Prawidłowy zakres z gsm, cdma, wcdma i lte: 0–65535.
Prawidłowy zakres z nr: 0–16777215.
mobileCountryCode number (uint32) Numer kierunkowy kraju stacji bazowej sieci komórkowej (MCK). Wymagany przez: radioType gsm (domyślny), wcdma, lte i nr; nieuż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.

Podane niżej pola opcjonalne nie są używane, ale mogą zostać uwzględnione, jeśli dostępne są wartości.

Pole Typ JSON Opis Uwagi
age number (uint32) Liczba milisekund od momentu, gdy ta komórka była główną. Jeśli wiek to 0, cellId lub newRadioCellId oznacza bieżący pomiar.
signalStrength number (double) Siła sygnału radiowego mierzona w dBm.
timingAdvance number (double) Wartość przebiegu w czasie.

Obliczam: cellId

Typy radiowe sprzed NR (5G) używają 32-bitowego pola cellId do przekazywania identyfikatora komórki sieciowej do interfejsu Geolocation API.

  • Sieci GSM (2G) korzystają z 16-bitowego identyfikatora komórki (CID) w niezmienionej postaci. Prawidłowy zakres: 0–65535.
  • Sieci CDMA (2G) korzystają z 16-bitowego identyfikatora stacji bazowej (bid) w niezmienionej postaci. Prawidłowy zakres to 0–65 535.
  • Sieci WCDMA (3G) używają UTRAN/GERAN Cell Identity (UC-ID), czyli 28-bitowej liczby całkowitej obejmującej 12-bitowy identyfikator RNC-ID i 16-bitowy identyfikator komórki (CID).
    Wzór: rnc_id << 16 | cid.
    Prawidłowy zakres: 0–268435455.
    Uwaga: podanie tylko 16-bitowej wartości identyfikatora komórki w sieciach WCDMA skutkuje nieprawidłowym wynikiem lub zerem wyników.
  • W sieciach LTE (4G) używana jest tożsamość komórki E-UTRAN (ECI), która jest 28-bitową liczbą całkowitą łączącą 20-bitowy identyfikator węzła E-UTRAN (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 komórki w sieciach LTE skutkuje nieprawidłowym wynikiem lub zerem wyników.

Umieszczenie wartości poza tymi zakresami w żądaniu do interfejsu API może spowodować niezdefiniowane zachowanie. Interfejs API może według własnego uznania Google skrócić liczbę, aby mieściła się w udokumentowanym zakresie, wywnioskować korektę 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, używają 64-bitowego pola newRadioCellId do przekazywania identyfikatora komórki sieciowej do interfejsu Geolocation API.

  • Sieci NR (5G) korzystają z 36-bitowej nowej tożsamości Radio Cell Identity (NCI).
    Prawidłowy zakres: 0–68719476735.

Poniżej znajduje się przykładowy obiekt stacji bazowej NR.

{
  "cellTowers": [
    {
      "newRadioCellId": 68719476735,
      "mobileCountryCode": 310,
      "mobileNetworkCode": 410,
      "age": 0,
      "signalStrength": -60,
    }
  ]
}

Obiekty punktu dostępu Wi-Fi

Tablica wifiAccessPoints 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 Uwagi
macAddress string Adres MAC węzła sieci Wi-Fi. Zwykle jest to adres BSS, BSSID lub MAC. Wymagane.Ciąg szesnastkowy rozdzielony dwukropkiem (:).
Interfejs API umożliwia znajdowanie tylko uniwersalnie administrowanych adresów MAC. Inne adresy MAC są dyskretnie pomijane, przez co żądanie do interfejsu API może stać się puste. Więcej informacji znajdziesz w sekcji Usuwanie 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 od -35 do 10 dBm i są w zakresie od -128 do -10 dBm. Pamiętaj, aby użyć znaku 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 obecnego sygnału do szumu mierzony w dB.

Poniżej znajduje się przykładowy obiekt punktu dostępu Wi-Fi.

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

Przykładowe żądania

Jeśli chcesz wypróbować interfejs Geolocation API z przykładowymi danymi, zapisz w pliku ten kod JSON:

{
  "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
    }
  ]
}

Następnie możesz użyć 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.4241876,
      "lng": -122.0917381
  },
  "accuracy": 32.839
}

Odrzucanie nieużywanych punktów dostępu Wi-Fi

Usunięcie obiektów punktu dostępu Wi-Fi z elementami macAddress, które są administrowane lokalnie, może poprawić wskaźnik sukcesu wywołań interfejsu Geolocation API, które wykorzystują Wi-Fi jako dane wejściowe. Jeśli po odfiltrowaniu danych okaże się, że wywołanie interfejsu Geolocation API nie powiedzie się, można zastosować środki łagodzące, takie jak użycie starszych sygnałów lokalizacyjnych lub punktów dostępu Wi-Fi o słabym sygnałach. To podejście stanowi kompromis między potrzebą oszacowania lokalizacji przez aplikację a wymaganiami dotyczącymi precyzji i czułości. Opisane poniżej techniki filtrowania pokazują, jak filtrować dane wejściowe, ale nie pokazują środków zaradczych, które może zastosować jako inżynier aplikacji.

Administrowane lokalnie adresy MAC nie są przydatne w przypadku interfejsu API i są pomijane w żądaniach. Możesz usunąć takie adresy MAC, upewniając się, że drugi mniej znaczący bit najbardziej istotnego bajtu funkcji macAddress to 0, np. 1 bit reprezentowany przez 2 w 02:00:00:00:00:00. Rozgłaszany adres MAC (FF:FF:FF:FF:FF:FF) to przykładowy adres MAC, który zostałby wykluczony przez ten filtr.

Zakres adresów MAC z zakresu od 00:00:5E:00:00:00 do 00:00:5E:FF:FF:FF jest zarezerwowany dla IANA i często używany na potrzeby funkcji zarządzania siecią i funkcji multiemisji, co wyklucza ich użycie jako sygnału lokalizacji. Musisz też usunąć te adresy MAC z danych wejściowych do interfejsu API.

Na przykład przydatne adresy MAC do geolokalizacji można uzyskać z tablicy ciągów znaków macAddress o nazwie macs:

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');

Użycie tego filtra spowoduje, że na liście pozostaną tylko 1c:34:56:78:9a:bc. Ponieważ ta lista zawiera mniej niż 2 adresy MAC sieci Wi-Fi, żądanie nie zostanie zrealizowane i zostanie zwrócona odpowiedź HTTP 404(notFound).

Odpowiedzi dotyczące geolokalizacji

Pomyślne żądanie geolokalizacji zwraca odpowiedź w formacie JSON z określeniem lokalizacji i promienia.

  • location: szacowana szerokość i długość geograficzna użytkownika (w stopniach). Zawiera 1 pole podrzędne lat i 1 pole podrzędne lng.
  • accuracy: dokładność orientacyjnej lokalizacji w metrach. Jest to promień okręgu wokół wybranego elementu (location).
{
  "location": {
    "lat": 37.421875199999995,
    "lng": -122.0851173
  },
  "accuracy": 120
}