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 domowej sieci 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 nieprawidłowe lub zerowe wyniki, 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, pustych sygnałów lub sygnałów niewystarczających 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 punktu dostępu Wi-Fi poniżej.

Poniżej znajduje się przykładowy tekst żą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 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 dla 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) dla 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).		 Wymagany.
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ę główną. Jeśli wiek wynosi 0, symbol cellId lub newRadioCellId oznacza bieżący pomiar.
signalStrength number (double) Siła sygnału radiowego mierzona w dBm.
timingAdvance number (double) Wartość wyprzedzenia czasowego.

Obliczanie 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ę do radioType lub zwrócić wynik NOT_FOUND bez żadnego wskaźnika w odpowiedzi.

Poniżej znajduje się przykład obiektu 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 sieci do interfejsu Geolocation API.

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

Poniżej znajdziesz przykładowy obiekt stacji bazowej NR.

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

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 urządzenia punktów dostępu. Pole macAddress jest wymagane, a wszystkie pozostałe pola są opcjonalne.

Pole Typ JSON Opis Uwagi
macAddress string Adres MAC węzła Wi-Fi. Zwykle nazywa się to BSS, BSSID lub adresem MAC. Wymagany. Ciąg szesnastkowy rozdzielony dwukropkami (:).
Tylko uniwersalne adresy MAC można lokalizować za pomocą interfejsu API. Pozostałe adresy MAC są cicho odrzucane, co może spowodować, że żądanie do interfejsu API będzie w praktyce puste. Szczegółowe informacje znajdziesz w sekcji 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 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 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 macAddresses, które są administrowane lokalnie, może zwiększyć odsetek udanych wywołań interfejsu Geolocation API, które używają Wi-Fi jako danych wejściowych. Jeśli po odfiltrowaniu 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 zakresu. Poniższe techniki filtrowania pokazują, jak filtrować dane wejściowe, ale nie przedstawiają środków, które możesz zastosować jako inżynier aplikacji.

Lokalnie administrowane 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. Musisz 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 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, która określa lokalizację i promień.

  • location: szacunkowe współrzędne geograficzne użytkownika (szerokość i długość) w stopniach. Zawiera 1 pole podrzędne lat i 1 pole podrzędne lng.
  • accuracy: dokładność szacowanej lokalizacji w metrach. Jest to promień okręgu wokół danego punktulocation.
{
  "location": {
    "lat": 37.421875199999995,
    "lng": -122.0851173
  },
  "accuracy": 120
}