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 jako wartość parametru key. key to klucz interfejsu API aplikacji. Ten klucz identyfikuje Twoją aplikację na potrzeby zarządzania limitami. Dowiedz się, jak uzyskać klucz.

Treść żądania

Treść żądania musi być sformatowana jako JSON. Jeśli treść żądania nie jest uwzględniona, wyniki są zwracane na podstawie adresu IP lokalizacji żądania. Obsługiwane są te pola (wszystkie są opcjonalne, o ile nie podano inaczej):

Pole	Typ JSON	Opis	Uwagi
`homeMobileCountryCode`	`number` (`uint32`)	Kod MCC sieci domowej urządzenia.	Obsługiwane 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 sieci domowej urządzenia. Jest to kod MNC dla sieci GSM, WCDMA, LTE i NR. CDMA używa identyfikatora systemu (SID).	Dozwolony zakres dla MNC: 0–999. Prawidłowy zakres identyfikatora SID: 0–32767.
`radioType`	`string`	Typ radia komórkowego. Obsługiwane wartości to `gsm`, `cdma`, `wcdma`, `lte` i `nr`.	To pole jest opcjonalne, ale powinno być zawsze uwzględniane, jeśli typ radia jest znany klientowi. Jeśli to pole zostanie pominięte, interfejs Geolocation API przyjmie domyślnie wartość `gsm`, co spowoduje zwrócenie nieprawidłowych lub zerowych wyników, jeśli założony typ radia jest nieprawidłowy.
`carrier`	`string`	Nazwa przewoźnika.
`considerIp`	`boolean`	Określa, czy w przypadku braku sygnałów Wi-Fi i stacji bazowych, ich pustych wartości lub niewystarczających danych do oszacowania lokalizacji urządzenia należy użyć geolokalizacji IP.	Domyślna wartość to `true`. Ustaw wartość `considerIp` na `false`, aby zapobiec powrotowi do poprzedniej wersji.
`cellTowers`	`array`	Tablica obiektów stacji bazowych.	Zapoznaj się z sekcją Obiekty stacji bazowych poniżej.
`wifiAccessPoints`	`array`	Tablica obiektów punktów dostępu Wi-Fi.	Więcej informacji znajdziesz w sekcji Obiekty punktów dostępu Wi-Fi poniżej.

Poniżej znajduje się przykładowy tekst żądania interfejsu Geolocation API.

{
  "homeMobileCountryCode": 310,
  "homeMobileNetworkCode": 410,
  "radioType": "lte",
  "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 zero lub więcej obiektów stacji bazowych.

Pole	Typ JSON	Opis	Uwagi
`cellId`	`number` (`uint32`)	Unikalny identyfikator komórki.	Wymagany w przypadku `radioType` `gsm` (domyślnie), `cdma`, `wcdma` i `lte`; odrzucony w przypadku `nr`. W sekcji Obliczanie identyfikatora komórki poniżej znajdziesz też listę zakresów prawidłowych wartości dla każdego typu radia.
`newRadioCellId`	`number` (`uint64`)	Unikalny identyfikator komórki NR (5G).	Wymagany w przypadku `radioType` `nr`; odrzucony w przypadku innych typów. Więcej informacji znajdziesz w sekcji Obliczanie wartości newRadioCellId poniżej. Znajduje się tam też lista prawidłowych zakresów wartości tego pola.
`locationAreaCode`	`number` (`uint32`)	Kod obszaru lokalizacji (LAC) dla sieci GSM i WCDMA. Identyfikator sieci (NID) w przypadku sieci CDMA. Kod obszaru śledzenia (TAC) w przypadku sieci LTE i NR.	Wymagany w przypadku wartości `radioType` `gsm` (domyślna) 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 `nr`: 0–16777215.
`mobileCountryCode`	`number` (`uint32`)	Kod kraju komórki (MCC) stacji bazowej.	Wymagany w przypadku `radioType` `gsm` (domyślnie), `wcdma`,`lte` i `nr`; nieużywany w przypadku `cdma`. Prawidłowy zakres: 0–999.
`mobileNetworkCode`	`number` (`uint32`)	Kod sieci komórkowej stacji bazowej. Jest to kod MNC dla sieci GSM, WCDMA, LTE i NR. CDMA używa identyfikatora systemu (SID).	Wymagane. Prawidłowy zakres dla MNC: 0–999. Prawidłowy zakres identyfikatora SID: 0–32767.

Te pola opcjonalne nie są używane, ale można je uwzględnić, jeśli są dostępne wartości.

Pole	Typ JSON	Opis	Uwagi
`age`	`number` (`uint32`)	Liczba milisekund od momentu, gdy ta komórka stała się podstawową.	Jeśli wiek wynosi 0, wartość `cellId` lub `newRadioCellId` oznacza bieżący pomiar.
`signalStrength`	`number` (`double`)	Siła sygnału radiowego mierzona w dBm.
`timingAdvance`	`number` (`double`)	Wartość wyprzedzenia czasowego.

Obliczam `cellId`

W przypadku typów radiowych starszych niż NR (5G) do przekazywania identyfikatora komórki sieci do interfejsu Geolocation API używane jest 32-bitowe pole cellId.

Sieci GSM (2G) używają 16-bitowego identyfikatora komórki (CID) w niezmienionej postaci. Prawidłowy zakres: 0–65535.
Sieci CDMA (2G) używają 16-bitowego identyfikatora stacji bazowej (BID) w niezmienionej postaci. Prawidłowy zakres: 0–65535.
Sieci WCDMA (3G) używają identyfikatora komórki UTRAN/GERAN (UC-ID), który jest 28-bitową liczbą całkowitą łączącą 12-bitowy identyfikator kontrolera sieci radiowej (RNC-ID) i 16-bitowy identyfikator komórki (CID).
Formuła: rnc_id << 16 | cid.
Prawidłowy zakres: 0–268435455.
Uwaga: podanie w sieciach WCDMA tylko 16-bitowej wartości identyfikatora komórki powoduje uzyskanie nieprawidłowych lub zerowych wyników.
Sieci LTE (4G) używają identyfikatora komórki E-UTRAN (ECI), który jest 28-bitową liczbą całkowitą łączącą 20-bitowy identyfikator węzła E-UTRAN B (eNBId) i 8-bitowy identyfikator komórki (CID).
Formuła: enb_id << 8 | cid.
Prawidłowy zakres: 0–268435455.
Uwaga: podanie w sieciach LTE tylko 8-bitowej wartości identyfikatora komórki powoduje uzyskanie nieprawidłowych lub zerowych wyników.

Umieszczenie w żądaniu API wartości spoza tych zakresów może spowodować nieokreślone działanie. Interfejs API może według uznania Google skrócić liczbę, aby zmieściła się w udokumentowanym zakresie, wywnioskować korektę wartości radioType lub zwrócić wynik NOT_FOUND bez żadnego wskaźnika w odpowiedzi.

Poniżej znajdziesz przykładowy obiekt stacji bazowej LTE, który jest częścią treści żądania.

{
  ...

  "cellTowers": [
    {
      "cellId": 170402199,
      "locationAreaCode": 35632,
      "mobileCountryCode": 310,
      "mobileNetworkCode": 410,
      "age": 0,
      "signalStrength": -60,
      "timingAdvance": 15
    }
  ]
}

Odpowiedź na poprzednie żądanie wygląda tak:

{
  "location": {
    "lat": 37.7801129,
    "lng": -122.4168229
  },
  "accuracy": 180.052
}

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 sieci do interfejsu Geolocation API.

Sieci NR (5G) używają 36-bitowego identyfikatora komórki New Radio Cell Identity (NCI) w niezmienionej postaci.
Prawidłowy zakres: 0–68719476735.

Poniżej znajdziesz przykładowy obiekt stacji bazowej NR, który jest częścią treści żądania.

{
  ...

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

Odpowiedź na powyższe żądanie wygląda tak:

{
  "location": {
    "lat": 37.7646157,
    "lng": -122.4127361
  },
  "accuracy": 1458.5570522410717
}

Obiekty punktów dostępu Wi-Fi

Tablica wifiAccessPoints w treści żądania musi zawierać co najmniej 2 obiekty punktów dostępu Wi-Fi reprezentujące fizycznie odrębne stacjonarne urządzenia punktów dostępu. Pole macAddress jest wymagane. Wszystkie pozostałe pola są opcjonalne. Usługa ignoruje punkty dostępu, które się przemieszczają, np. w samolotach i pociągach.

Pole	Typ JSON	Opis	Uwagi
`macAddress`	`string`	Adres MAC węzła Wi-Fi. Zwykle nazywa się go BSS, BSSID lub adresem MAC.	Wymagany. Ciąg szesnastkowy rozdzielony dwukropkami (`:`). Tylko uniwersalne adresy MAC można lokalizować za pomocą interfejsu API. Inne adresy MAC są cicho odrzucane, co może spowodować, że żądanie do interfejsu API stanie się puste. Szczegółowe informacje znajdziesz w artykule Usuwanie nieużywanych punktów dostępu Wi-Fi.
`signalStrength`	`number` (`double`)	Obecna siła sygnału mierzona w dBm.	W przypadku punktów dostępu Wi-Fi wartości dBm wynoszą zwykle -35 lub mniej i mieszczą się w zakresie od -128 do -10 dBm. Pamiętaj o znaku minusa. W przypadku wartości większych niż -10 dBm interfejs API zwraca `NOT FOUND`.
`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`)	Aktualny stosunek sygnału do szumu mierzony w dB.

Poniżej znajdziesz przykładowy obiekt punktu dostępu Wi-Fi, który jest częścią treści żądania.

{
  ...
  
  "macAddress": "f0:d5:bf:fd:12:ae",
  "signalStrength": -43,
  "signalToNoiseRatio": 0,
  "channel": 11,
  "age": 0
}

Odpowiedź na poprzednie żądanie wygląda tak:

{
  "location": {
    "lat": 37.7801129,
    "lng": -122.4168229
  },
  "accuracy": 180.052
}

Przykładowe żądania

Jeśli chcesz wypróbować interfejs Geolocation API na przykładowych danych, zapisz poniższy 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 poziomu 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 powyższych 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 punktów dostępu Wi-Fi z macAddress, które są administrowane lokalnie, może zwiększyć odsetek udanych wywołań interfejsu Geolocation API, które wykorzystują Wi-Fi jako dane wejściowe. Jeśli po filtrowaniu można stwierdzić, że wywołanie interfejsu Geolocation API nie powiedzie się, można zastosować środki zaradcze, takie jak użycie starszych sygnałów lokalizacji lub punktów dostępu Wi-Fi o słabszych sygnałach. To kompromis między potrzebą aplikacji w zakresie szacowania lokalizacji a wymaganiami dotyczącymi precyzji i pełności. Poniższe techniki filtrowania pokazują, jak filtrować dane wejściowe, ale nie przedstawiają środków, które możesz zastosować jako inżynier aplikacji.

Lokalne adresy MAC nie są przydatnymi sygnałami lokalizacji dla interfejsu API i są cicho usuwane z żądań. Możesz usunąć takie adresy MAC, upewniając się, że drugi najmniej znaczący bit najbardziej znaczącego bajtu adresu macAddress ma wartość 0, np. bit 1 reprezentowany przez 2 w adresie 02:00:00:00:00:00. Adres MAC transmisji (FF:FF:FF:FF:FF:FF) to przykład adresu MAC, który warto wykluczyć za pomocą tego filtra.

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 używany do zarządzania siecią oraz funkcji multiemisji, co uniemożliwia ich wykorzystanie jako sygnału lokalizacji. Powinieneś też usunąć te adresy MAC z danych wejściowych interfejsu API.

Na przykład adresy MAC, które można wykorzystać w geolokalizacji, można zebrać z tablicy macAddress ciągów znaków 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');

Po zastosowaniu tego filtra na liście pozostanie tylko 1c:34:56:78:9a:bc. Ponieważ ta lista zawiera mniej niż 2 adresy MAC 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, która określa lokalizację i promień.

location: szacunkowe współrzędne geograficzne użytkownika (szerokość i długość) w stopniach. Zawiera jedno pole lat i jedno pole lng.
accuracy: dokładność szacowanej lokalizacji w metrach. Oznacza to promień okręgu wokół danego punktulocation.

{
  "location": {
    "lat": 37.421875199999995,
    "lng": -122.0851173
  },
  "accuracy": 120
}

Interfejs API zwraca lokalizację i promień dokładności na podstawie sygnałów wejściowych. Interfejs API może zwracać bardzo dokładną lokalizację, ale dokładność może się różnić w zależności od źródła, liczby, gęstości i siły dostępnych sygnałów. Zwykle możesz oczekiwać następujących promieni dokładności:

Punkty dostępu Wi-Fi: jeśli żądanie zawiera co najmniej 2 wifiAccessPoints, zwrócony promień dokładności wynosi zwykle około 20 metrów. Dokładność wzrasta wraz z liczbą punktów dostępu i siłą sygnałów (mierzoną w dBm), która zwykle waha się od -100 do -20 dBm.
Stacje bazowe: jeśli informacje o Wi-Fi są niedostępne lub niewystarczające, interfejs API używa cellTowers do określania lokalizacji. Dokładność znacznie się różni w zależności od typu stacji bazowej, siły sygnału i gęstości sieci:
- Makrokomórki (najpopularniejszy typ, używany do pokrywania dużych obszarów) zapewniają mniejszą dokładność. Promień wynosi zwykle kilkaset metrów, a na obszarach o rzadkim pokryciu stacjami bazowymi może sięgać kilku tysięcy metrów. W przypadku makrokomórek rzadko udaje się osiągnąć promień dokładności poniżej 100 metrów. Dokładność jest zwykle większa w przypadku stacji bazowych z silnym sygnałem. Silne sygnały mają zwykle wartość > –110 dBm w przypadku LTE (zakres sygnału od –140 do –55 dBm), > –100 dBm w przypadku WCDMA (zakres sygnału od –111 do –53 dBm), > –100 dBm w przypadku CDMA (zakres sygnału od –120 do –40 dBm) i > –80 dBm w przypadku GSM (zakres sygnału od –121 do –1 dBm).
- Małe komórki (np. femtokomórki, pikokomórki lub wzmacniacze sygnału w pomieszczeniach) zapewniają najbardziej precyzyjną lokalizację na podstawie komórki, a promień dokładności może wynosić od 10 do 30 metrów.
Geolokalizacja IP: jeśli wartość considerIp to true i nie można określić lokalizacji na podstawie sygnałów Wi-Fi ani stacji bazowych, interfejs API szacuje lokalizację na podstawie adresu IP żądania. Ta metoda zapewnia najmniejszą dokładność, a promienie mogą wynosić tysiące metrów. Zobacz Dlaczego promień dokładności jest bardzo duży? w przewodniku rozwiązywania problemów.