Prośba o geolokalizację i odpowiedź

Prośby o geolokalizację

Zapytania o lokalizację są wysyłane za pomocą metody POST pod 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 Twojej aplikacji. Ten klucz identyfikuje Twoją aplikację na potrzeby zarządzania limitami. Dowiedz się, jak uzyskać klucz.

Treść żądania

Treść żądania musi być sformatowana w formacie JSON. Jeśli nie podasz treści żądania, wyniki zostaną zwrócone na podstawie adresu IP lokalizacji żądania. Obsługiwane są te pola: wszystkie pola są opcjonalne, chyba że zaznaczono inaczej:

Pole Typ pliku JSON Opis Uwagi
homeMobileCountryCode number (uint32) Kod kraju (MCC) domowej sieci 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 dla domowej sieci urządzenia. Jest to MNC dla GSM, WCDMA, LTE i NR.
CDMA używa identyfikatora systemu (SID).		 Ważliwy zakres dla MNC: 0–999.
Prawidłowy zakres identyfikatora SID: 0–32767.
radioType string Typ radia mobilnego. Obsługiwane wartości to gsm, cdma, wcdma, lte i nr. To pole jest opcjonalne, ale należy je zawsze uwzględnić, jeśli klient zna typ radia.
Jeśli pole zostanie pominięte, Geolocation API przyjmie domyślnie wartość gsm, co spowoduje nieprawidłowe wyniki lub brak wyników, jeśli zadeklarowany typ radia jest nieprawidłowy.
carrier string Nazwa przewoźnika.
considerIp boolean Określa, czy w przypadku braku sygnału z sieci Wi-Fi lub wieży komórkowej, pustego sygnału lub sygnału niewystarczającego do oszacowania lokalizacji urządzenia, należy przejść na geolokalizację na podstawie adresu IP. Domyślna wartość to true. Aby zapobiec użyciu wartości domyślnej, ustaw wartość considerIp na false.
cellTowers array Tablica obiektów wieży telefonii komórkowej. Zapoznaj się z sekcją Obiekty wież komórkowych 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 znajdziesz przykład treści żądania 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 może zawierać 0 lub więcej obiektów wieży komórkowej.

Pole Typ pliku 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.
Zapoznaj się z sekcją Obliczanie cellId poniżej, w której znajdziesz również listę prawidłowych zakresów wartości dla każdego typu radio.
newRadioCellId number (uint64) Unikalny identyfikator komórki NR (5G). Wymagany w przypadku radioType nr; odrzucony w przypadku innych typów.
Zobacz sekcję Obliczanie newRadioCellId poniżej, która zawiera też listę prawidłowych wartości tego pola.
locationAreaCode number (uint32) Kod obszaru lokalizacji (LAC) dla sieci GSM i WCDMA.
Identyfikator sieci (NID) dla sieci 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 dla atrybutów gsm, cdma, wcdma i lte: 0–65535.
Prawidłowy zakres dla nr: 0–16777215.
mobileCountryCode number (uint32) Kod kraju komórkowego (MCC) stacji bazowej. Wymagany w przypadku radioType gsm (domyślny), wcdma, lte i nr; nie jest używany w przypadku 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).		 Wymagany.
Prawidłowy zakres dla MNC: 0–999.
Prawidłowy zakres wartości SID: 0–32767.

Te opcjonalne pola nie są używane, ale mogą być uwzględnione, jeśli są dostępne wartości.

Pole Typ pliku JSON Opis Uwagi
age number (uint32) Liczba milisekund od momentu, gdy ta komórka była komórką docelową. Jeśli wartość age wynosi 0, wartość 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 radia w wersjach starszych niż 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) bez zmian. Dopuszczalny zakres: 0–65535.
  • Sieci CDMA (2G) używają 16-bitowego identyfikatora stacji bazowej (BID) bez zmian. Dopuszczalny zakres: 0–65535.
  • Sieci WCDMA (3G) używają identyfikatora komórki UTRAN/GERAN (UC-ID), który jest 28-bitową wartością 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 nieprawidłowe wyniki lub brak wyników.
  • Sieci LTE (4G) używają identyfikatora komórki E-UTRAN (ECI), który jest 28-bitową wartością całkowitą, zawierają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 nieprawidłowe wyniki lub brak wyników.

Podanie w żądaniu API wartości spoza tych zakresów może spowodować nieokreślone działanie. Interfejs API może według własnego uznania przyciąć liczbę, aby pasowała do udokumentowanego zakresu, wywnioskować poprawkę do radioType lub zwrócić wynik NOT_FOUND bez żadnego wskaźnika w odpowiedzi.

Poniżej znajduje się przykład obiektu wieży komórkowej LTE.

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

ObliczamnewRadioCellId

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 nowej komórki radiowej (NCI) bez zmian.
    Dopuszczalny zakres: 0–68719476735.

Poniżej znajdziesz przykład obiektu wieży komórkowej 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 punktu dostępu Wi-Fi reprezentujące fizycznie różne urządzenia punktu dostępu. Pole macAddress jest wymagane, a pozostałe pola są opcjonalne.

Pole Typ pliku 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 rozdzielony dwukropkami (:).
Za pomocą interfejsu API można zlokalizować tylko adresy MAC administrowane globalnie. Inne adresy MAC są po cichu odrzucane i mogą spowodować, że żądanie interfejsu API stanie się puste. Szczegółowe informacje znajdziesz w sekcji Usuwanie niepotrzebnych punktów dostępu do 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 zwykle wynoszą -35 dBm lub mniej i wahają się w zakresie od -128 do -10 dBm. Pamiętaj, aby umieścić znak minusa.
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) Aktualny stosunek sygnału do szumu mierzony w dB.

Poniżej przedstawiono 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 na przykładowych danych, zapisz w pliku następujący ciąg JSON:

{
  "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 przesł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
}

Odrzucanie nieużywanych punktów dostępu Wi-Fi

Usunięcie obiektów punktów dostępu Wi-Fi z macAddress, które są zarządzane lokalnie, może zwiększyć skuteczność wywołań Geolocation API, które używają Wi-Fi jako danych wejściowych. Jeśli po przefiltrowaniu okaże się, że wywołanie interfejsu Geolocation API zakończy się niepowodzeniem, można zastosować środki zaradcze, takie jak użycie starszych sygnałów lokalizacji lub punktów dostępu Wi-Fi z słabszymi sygnałami. To podejście jest kompromisem między potrzebą aplikacji w zakresie oszacowania lokalizacji a jej wymaganiami dotyczącymi dokładności i wywołalności. Podane niżej techniki filtrowania pokazują, jak filtrować dane wejściowe, ale nie pokazują środków zaradczych, które możesz zastosować jako inżynier aplikacji.

Adresy MAC zarządzane lokalnie nie są przydatnymi sygnałami lokalizacji dla interfejsu API i automatycznie są usuwane z żądań. Możesz usunąć takie adresy MAC, upewniając się, że drugi najmniej istotny bit najbardziej istotnego bajtu adresu macAddress to 0, np. 1 bit reprezentowany przez 2 w 02:00:00:00:00:00. Adres MAC rozgłoszeniowy (FF:FF:FF:FF:FF:FF) to przykład adresu MAC, który zostanie wykluczony przez ten filtr.

Zakres adresów MAC między 00:00:5E:00:00:00 a 00:00:5E:FF:FF:FF jest zarezerwowany dla IANA i często używany do zarządzania siecią oraz funkcji multicast, co uniemożliwia ich użycie jako sygnału lokalizacji. Musisz też usunąć te adresy MAC z danych wejściowych interfejsu API.

Na przykład użyteczne adresy MAC do geolokalizacji można zebrać 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');

Zastosowanie tego filtra spowoduje, że na liście pozostanie tylko 1c:34:56:78:9a:bc. Ponieważ na liście jest mniej niż 2 adresy MAC sieci Wi-Fi, żądanie nie zostanie zrealizowane i zwrócona zostanie odpowiedź HTTP 404 (notFound).

Odpowiedzi dotyczące geolokalizacji

Pomyślne żądanie geolokalizacji zwraca odpowiedź w formacie JSON z określoną lokalizacją i jej promieniem.

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