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 podany 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. Poniższe pola są obsługiwane i 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 przez cdma.
Prawidłowy zakres: 0–999.
homeMobileNetworkCode number (uint32) Kod sieci komórkowej domowej na urządzeniu. Jest 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 identyfikatora SID: 0–32767.
radioType string Typ radia na urządzeniu mobilnym. Obsługiwane wartości to gsm, cdma, wcdma, lte i nr. To pole jest opcjonalne, ale powinno być zawsze uwzględniane, jeśli klient znany jest typowi radiowej.
Jeśli to pole zostanie pominięte, interfejs Geolocation API domyślnie przyjmuje wartość gsm, co spowoduje zwracanie nieprawidłowych lub zerowych wyników w przypadku nieprawidłowego typu odbiornika radiowego.
carrier string Nazwa przewoźnika.
considerIp boolean Określa, czy powrócić do geolokalizacji IP, jeśli brakuje sygnałów Wi-Fi i masztów telefonii komórkowej, są one puste lub są niewystarczające do oszacowania lokalizacji urządzenia. Domyślna wartość to true. Ustaw considerIp na false, aby uniknąć awaryjnego działania.
cellTowers array Tablica obiektów na masztach komórkowych. Przeczytaj sekcję Obiekty w maszynie komórkowej poniżej.
wifiAccessPoints array Tablica obiektów punktów dostępu Wi-Fi. Przeczytaj sekcję Obiekty punktu dostępu Wi-Fi poniżej.

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

Tablica cellTowers w treści żądania zawiera 0 lub więcej 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 elementu nr.
Zapoznaj się poniżej z sekcją Obliczanie identyfikatora komórki, która zawiera również listę prawidłowych zakresów wartości dla każdego typu radia.
newRadioCellId number (uint64) Unikalny identyfikator komórki NR (5G). Wymagany dla: radioType nr; odrzucony w przypadku innych typów.
Zapoznaj się z sekcją Obliczanie pola newRadioCellId poniżej, która zawiera też prawidłowy zakres wartości pola.
locationAreaCode number (uint32) Kod lokalizacji (LAC) w przypadku sieci GSM i WCDMA.
Identyfikator sieci (NID) dla sieci CDMA.
Kod obszaru śledzenia (TAC) dla sieci LTE i NR.		 Wymagany dla radioType gsm (domyślny) i cdma; opcjonalny w przypadku innych wartości.
Prawidłowy zakres to gsm, cdma, wcdma i lte: 0–65 535.
Prawidłowy zakres z nr: 0–16777215.
mobileCountryCode number (uint32) Kod kraju stacji bazowej (MCK) Wymagany przez: radioType gsm (domyślny), wcdma, lte i nr; nieużywany przez cdma.
Prawidłowy zakres: 0–999.
mobileNetworkCode number (uint32) Kod sieci komórkowej stacji bazowej. Jest 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 identyfikatora SID: 0–32767.

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

Pole Typ JSON Opis Uwagi
age number (uint32) Liczba milisekund od momentu utworzenia komórki jako podstawowej. Jeśli wiek wynosi 0, cellId lub newRadioCellId oznacza bieżący pomiar.
signalStrength number (double) Siła sygnału radiowego mierzona w dBm.
timingAdvance number (double) Wartość czasu wyprzedzenia.

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–65 535.
  • Sieci CDMA (2G) używają 16-bitowego identyfikatora stacji bazowej (BID) w niezmienionej postaci. Prawidłowy zakres: 0–65 535.
  • Sieci WCDMA (3G) korzystają z UTRAN/GERAN Cell Identity (UC-ID), czyli 28-bitowej liczby całkowitej łączą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.
  • Sieci LTE (4G) korzystają z E-UTRAN Cell Identity (ECI), który 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 wartości 8-bitowego identyfikatora komórki w sieciach LTE skutkuje nieprawidłowym wynikiem lub zerem wyników.

Jeśli w żądaniu do interfejsu API znajdują się wartości spoza tych zakresów, może to spowodować niezdefiniowane zachowanie. Interfejs API może według własnego uznania skrócić numer, tak aby mieścił się w udokumentowanym zakresie, wywnioskować poprawkę na 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, wykorzystują 64-bitowe pole 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 sieci komórkowej 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 Wi-Fi. Zwykle jest to adres BSS, BSSID lub MAC. Wymagane.Ciąg szesnastkowy rozdzielony dwukropkiem (:).
Za pomocą interfejsu API można znaleźć tylko uniwersalnie administrowane adresy MAC. Inne adresy MAC są dyskretne pomijane i mogą sprawić, że żądanie do interfejsu API stanie się puste. Więcej informacji znajdziesz w sekcji Usuwanie bezużytecznych 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 nie przekraczają zwykle -35 dBm i mają zakres 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 ten kod JSON w pliku:

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

Możesz potem 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
}

Pomijanie 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 przefiltrowaniu zostanie uznane, że wywołanie interfejsu API geolokalizacji 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łabych sygnałach. To podejście stanowi kompromis między wymaganiami aplikacji dotyczącymi oszacowania lokalizacji a 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ą przydatne w przypadku sygnałów dotyczących lokalizacji dla interfejsu API i są bez powiadomienia usuwane z żądań. Możesz usunąć takie adresy MAC, upewniając się, że drugi najmniej ważny bit najbardziej istotnego bajtu elementu macAddress to 0, np. 1 bit reprezentowany przez 2 w 02:00:00:00:00:00. Przykład adresu MAC transmisji (FF:FF:FF:FF:FF:FF) 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 do zarządzania siecią i funkcji multiemisji, co uniemożliwia ich użycie jako sygnału lokalizacyjnego. Należy też usunąć te adresy MAC z danych wejściowych do interfejsu API.

Na przykład użyteczne 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');

Po użyciu tego filtra 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 zwrócony zostanie błąd HTTP 404 (notFound).

Odpowiedzi na temat geolokalizacji

Pomyślne żądanie geolokalizacji zwraca odpowiedź w formacie JSON definiującą lokalizację i promień.

  • location: szacowana szerokość i długość geograficzna użytkownika (w stopniach). Zawiera jedno pole lat i jedno pole podrzędne lng.
  • accuracy: dokładność szacowanej lokalizacji w metrach. Jest to promień koła wokół podanej wartości location.
{
  "location": {
    "lat": 37.421875199999995,
    "lng": -122.0851173
  },
  "accuracy": 120
}