Prośba o geolokalizację i odpowiedź

Żądania geolokalizacji

Żą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 pola są opcjonalne, chyba że zaznaczono inaczej:

Pole Typ JSON Opis Uwagi
homeMobileCountryCode number (uint32) Kod kraju (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 MNC sieci domowej urządzenia. Jest to kod MNC dla GSM, WCDMA, LTE i NR.
CDMA używa identyfikatora systemu (SID)		 Prawidłowy zakres 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 klient zna typ sieci komórkowej.
Jeśli pole zostanie pominięte, interfejs Geolocation API domyślnie przyjmie wartość gsm, co może spowodować nieprawidłowe lub zerowe wyniki, jeśli założony typ sieci komórkowej jest nieprawidłowy.
carrier string Nazwa przewoźnika.
considerIp boolean Określa, czy w przypadku braku sygnałów Wi-Fi i stacji bazowej, ich pustych wartości lub niewystarczającej siły do oszacowania lokalizacji urządzenia ma być używana geolokalizacja IP. Domyślna wartość to true. Ustaw considerIp na false, aby zapobiec powrotowi do poprzedniej wersji.
cellTowers array Tablica obiektów stacji bazowych. Zobacz sekcję Obiekty stacji bazowych poniżej.
wifiAccessPoints array Tablica obiektów punktów dostępu Wi-Fi. Zobacz sekcję Obiekty punktów dostępu Wi-Fi poniżej.

Poniżej znajduje się przykład treści żądania do 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 co najmniej 1 obiekt stacji bazowej.

Pole Typ JSON Opis Uwagi
cellId number (uint32) Unikalny identyfikator komórki. Wymagany w przypadku radioType gsm (domyślnie), cdma, wcdma i lte; odrzucany w przypadku nr.
Zapoznaj się z sekcją Obliczanie identyfikatora cellId poniżej, w której znajdziesz też prawidłowe zakresy wartości dla poszczególnych typów sieci komórkowej.
newRadioCellId number (uint64) Unikalny identyfikator komórki NR (5G). Wymagany w przypadku radioType nr; odrzucany w przypadku innych typów.
Zapoznaj się z sekcją Obliczanie wartości newRadioCellId poniżej, w której znajdziesz też zakres prawidłowych wartości tego pola.
locationAreaCode number (uint32) Kod obszaru lokalizacji (LAC) dla sieci GSM i WCDMA.
Identyfikator sieci (NID) w sieciach CDMA.
Kod obszaru śledzenia (TAC) dla sieci LTE i NR.		 Wymagany w przypadku radioType gsm (domyślnie) 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) Kod kraju stacji bazowej (MCC). 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 MNC stacji bazowej. Jest to kod MNC dla GSM, WCDMA, LTE i NR.
CDMA używa identyfikatora systemu (SID).		 Parametr wymagany.
Prawidłowy zakres MNC: 0–999.
Prawidłowy zakres identyfikatora SID: 0–32767.

Te opcjonalne pola 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, gdy ta komórka była podstawowa. Jeśli wiek wynosi 0, cellId lub newRadioCellId reprezentuje bieżący pomiar.
signalStrength number (double) Siła sygnału radiowego mierzona w dBm.
timingAdvance number (double) Wartość wyprzedzenia czasowego.

Obliczam: cellId

Typy połączeń radiowych sprzed 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ó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 tylko 16-bitowej wartości identyfikatora komórki w sieciach WCDMA spowoduje, że wyniki będą nieprawidłowe lub zerowe.
  • Sieci LTE (4G) używają identyfikatora komórki E-UTRAN (ECI), który jest 28-bitową wartością całkowitą łączącą 20-bitowy identyfikator węzła B E-UTRAN (eNBId) i 8-bitowy identyfikator komórki (CID).
    Formuła: enb_id << 8 | cid.
    Prawidłowy zakres: 0–268435455.
    Uwaga: podanie tylko 8-bitowej wartości identyfikatora komórki w sieciach LTE spowoduje, że wyniki będą nieprawidłowe lub zerowe.

Umieszczenie wartości spoza tych zakresów w żądaniu do interfejsu API może spowodować nieokreślone działanie. Interfejs API może według uznania Google obciąć liczbę, 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 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
}

Obliczanie 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 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 poprzednie żą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ę to adresem BSS, BSSID lub MAC. Wymagany. Ciąg szesnastkowy oddzielony dwukropkami (:).
Za pomocą interfejsu API można lokalizować tylko adresy MAC administrowane uniwersalnie. Inne adresy MAC są odrzucane bez powiadomienia, co może spowodować, że żądanie do interfejsu API będzie puste. Więcej informacji znajdziesz w artykule Usuwanie nieprzydatnych 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 mieszczą się w zakresie od –128 do –10 dBm. Pamiętaj, aby uwzględnić znak 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ł, przez który klient komunikuje się z punktem dostępu.
signalToNoiseRatio number (double) Bieżący 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ć 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": "30:86:2d:c4:29:d0",
      "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ź dotycząca 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 punktów dostępu Wi-Fi z macAddress, które są adresem rozgłoszeniowym (FF:FF:FF:FF:FF:FF) lub są zarezerwowane przez IANA, może poprawić wskaźnik sukcesu wywołań interfejsu Geolocation API, które używają Wi-Fi jako danych wejściowych. Jeśli po filtrowaniu można ustalić, ż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 ze słabszymi sygnałami. To podejście stanowi kompromis między potrzebą oszacowania lokalizacji przez aplikację a wymaganiami dotyczącymi precyzji i czułości. Poniższe techniki filtrowania pokazują, jak filtrować dane wejściowe, ale nie pokazują środków zaradczych, które możesz zastosować jako inżynier aplikacji.

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ą i funkcji multiemisji, co uniemożliwia ich użycie jako sygnału lokalizacji. Należy też usunąć te adresy MAC z danych wejściowych interfejsu API.

Na przykład adresy MAC, których można użyć do geolokalizacji, można zebrać z tablicy ciągów znaków macAddress o nazwie macs:

Java
String[] macs = {"ff:ff:ff:ff:ff:ff", "1c:34:56:78:9a:bc", "00:00:5e:00:00:01"};
ArrayList<String> _macs = new ArrayList<>(Arrays.asList(macs));
_macs.removeIf(m -> !(!m.toUpperCase().equals("FF:FF:FF:FF:FF:FF")
                      && !m.substring(0, 8).toUpperCase().equals("00:00:5E")));
Python
macs = ['ff:ff:ff:ff:ff:ff', '1c:34:56:78:9a:bc', '00:00:5e:00:00:01']
macs = [m for m in macs if (m.upper() != "FF:FF:FF:FF:FF:FF" and m[:8].upper() != '00:00:5E')]
JavaScript
macs = ['ff:ff:ff:ff:ff:ff', '1c:34:56:78:9a:bc', '00:00:5e:00:00:01'];
macs = macs.filter(m => m.toUpperCase() !== "FF:FF:FF:FF:FF:FF"
                        && 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 geolokalizacyjne

Pomyślne żądanie geolokalizacji zwraca odpowiedź w formacie JSON, która określa lokalizację i promień.

  • location: szacowane współrzędne geograficzne użytkownika w stopniach. Zawiera jedno pole podrzędne lat i jedno pole podrzędne lng.
  • accuracy: dokładność orientacyjnej lokalizacji w metrach. Reprezentuje promień okręgu wokół podanego location.
{
  "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 się spodziewać następujących promieni dokładności:

  • Punkty dostępu Wi-Fi: jeśli żądanie zawiera co najmniej 2 wifiAccessPoints, zwracany promień dokładności wynosi zwykle około 20 metrów. Dokładność zwiększa się wraz z liczbą punktów dostępu i siłą sygnału (mierzoną w dBm). Siła sygnału zwykle wynosi 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ść różni się znacznie w zależności od typu stacji bazowej, siły sygnału i gęstości sieci:
    • Makrokomórki (najpopularniejszy typ, używany do pokrycia dużego obszaru) zapewniają mniejszą dokładność. Promień wynosi zwykle kilkaset metrów, ale na obszarach z niewielką liczbą stacji bazowych 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 o silnym sygnale. Silne sygnały to zwykle > -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 budynkach) zapewniają najbardziej precyzyjną lokalizację komórkową, z promieniem dokładności w zakresie 10–30 metrów.
  • Geolokalizacja IP: jeśli parametr considerIp ma wartość true i nie można geolokalizować sygnałów Wi-Fi ani stacji bazowej, interfejs API szacuje lokalizację na podstawie adresu IP żądania. Ta metoda zapewnia najniższą dokładność, a promień może wynosić tysiące metrów. Zobacz Dlaczego promień dokładności jest bardzo duży?. w przewodniku rozwiązywania problemów.