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 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. 1 bit reprezentowany przez 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:

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 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 pole lat i 1 pole podrzędne lng.
  • accuracy: dokładność szacowanej lokalizacji w metrach. Reprezentuje promień okręgu wokół podanej wartości location.
{
  "location": {
    "lat": 37.421875199999995,
    "lng": -122.0851173
  },
  "accuracy": 120
}