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 identyfikator Twojej aplikacji klucz interfejsu API. Ten klucz identyfikuje aplikację na potrzeby limitów i zarządzania nimi. Dowiedz się, jak uzyskać klucz.

Treść żądania

Treść żądania musi być w formacie JSON. Jeśli nie podasz treści żądania, wyniki są zwracane na podstawie adresu IP lokalizacji żądania. Wymienione niżej pola to obsługiwane i wszystkie pola są opcjonalne, o ile nie określono inaczej:

Pole Typ JSON Opis Uwagi
homeMobileCountryCode number (uint32) Kod kraju mobilnego (MCK) 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 w sieci domowej urządzenia. 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 SID: 0–32767.
radioType string Typ nadajnika na telefon komórkowy. Obsługiwane wartości to gsm, cdma, wcdma, lte i nr. To pole jest opcjonalne, ale powinno być zawsze uwzględniane, jeśli typ opcji to znane klientowi.
Jeśli to pole zostanie pominięte, interfejs Geolocation API domyślnie ustawi wartość gsm, co zwraca wyniki nieprawidłowe lub zerowe, jeśli zakładany typ opcji to niepoprawnie.
carrier string Nazwa przewoźnika.
considerIp boolean Określa, czy w razie braku sygnałów Wi-Fi i stacji bazowych sieci komórkowych stosować geolokalizację IP. jest puste lub niewystarczające do oszacowania lokalizacji urządzenia. Domyślna wartość to true. Aby zapobiec użyciu wartości domyślnej, ustaw wartość 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. Zobacz 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 może zawierać 0 lub więcej obiektów wieży komórkowej.

Pole Typ JSON Opis Uwagi
cellId number (uint32) Unikalny identyfikator komórki. Wymagany w przypadku aplikacji radioType gsm (domyślnie), cdma, wcdma i lte; odrzucone dla nr.
Przeczytaj sekcję Obliczanie identyfikatora komórki poniżej, która zawiera też listę prawidłowe zakresy wartości dla każdego typu opcji.
newRadioCellId number (uint64) Unikalny identyfikator komórki NR (5G). Wymagany w przypadku aplikacji radioType nr; odrzucone dla innego .
Zobacz sekcję Obliczanie newRadioCellId poniżej, w której znajdziesz też listę prawidłowych wartości 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 obszaru śledzenia (TAC) w sieciach LTE i NR.
Wymagany w przypadku aplikacji 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 aplikacji radioType gsm (domyślnie), wcdma, lte i nr; nieużywane w przypadku cdma.
Prawidłowy zakres: 0–999.
mobileNetworkCode number (uint32) Kod sieci komórkowej stacji bazowej. 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 SID: 0–32767.

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

Pole Typ JSON Opis Uwagi
age number (uint32) Liczba milisekund od czasu, gdy ta komórka była główna. Jeśli wiek to 0, cellId lub newRadioCellId oznacza aktualną wartość pomiar skuteczności.
signalStrength number (double) Siła sygnału radiowego mierzona w dBm.
timingAdvance number (double) przedział czasu .

Obliczanie: cellId

Typy radiowe przed NR (5G) używają 32-bitowego pola cellId do przekazywania sieci identyfikator komórki do interfejsu Geolocation API.

  • Sieci GSM (2G) używają 16-bitowego identyfikatora komórki (CID) w postaci domyślnej. Dopuszczalny zakres: 0–65535.
  • Sieci CDMA (2G) używają 16-bitowego identyfikatora stacji bazowej (BID). Prawidłowy zakres: 0–65 535.
  • Sieci WCDMA (3G) używają identyfikatora UTRAN/GERAN Cell Identity (UC-ID), który jest 28-bitową liczbą całkowitą. wartość stanowiąca połączenie 12-bitowego identyfikatora kontrolera sieci radiowej (RNC-ID) i 16-bitowego identyfikatora Identyfikator sieci komórkowej (ID klienta).
    Foruła: rnc_id << 16 | cid.
    Prawidłowy zakres: 0–268435455.
    Uwaga: określenie tylko 16-bitowej wartości identyfikatora Cell ID w sieciach WCDMA powoduje nieprawidłowych lub nieprawidłowych wyników.
  • Sieci LTE (4G) korzystają z protokołu E-UTRAN Cell Identity (ECI), czyli 28-bitowej liczby całkowitej. połączenie 20-bitowego identyfikatora węzła E-UTRAN B (eNBId) i 8-bitowego identyfikatora komórki (CID).
    Wzór: enb_id << 8 | cid.
    Prawidłowy zakres: 0–268435455.
    Uwaga: określenie tylko 8-bitowej wartości identyfikatora Cell ID w sieciach LTE powoduje nieprawidłowych lub nieprawidłowych wyników.

Znalezienie wartości poza tymi zakresami w żądaniu do interfejsu API może spowodować niezdefiniowane zachowanie. 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
    }
  ]
}

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-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ć dwa lub więcej obiektów punktu dostępu Wi-Fi. Pole macAddress jest wymagane; wszystkie a inne 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 rozdzielany kolumnami (:).
Tylko dostępne powszechnie Adresy MAC można znajdować za pomocą interfejsu API. Inne adresy MAC dyskretnie pominięte i może doprowadzić do tego, że żądanie API puste. Szczegółowe informacje znajdziesz w sekcji Rezygnacja z bezużytecznego dostępu do Wi-Fi punktów.
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ładem zapisz w pliku następujący kod 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 wpisz polecenie w wierszu 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

Usuwanie obiektów punktu dostępu Wi-Fi, które macAddresslokalnie administrowane może zwiększyć wskaźnik sukcesu wywołań interfejsu API geolokalizacji, 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 stanowi kompromis potrzeby aplikacji szacowania lokalizacji oraz jej dokładności i czułości . Poniższe techniki filtrowania pokazują, jak filtrować danych wejściowych, ale nie pokazuje środków zaradczych, które można zastosować. inżyniera, wybierz się do programu.

Lokalnie administrowane adresy MAC nie są przydatnymi sygnałami lokalizacji dla: API i są dyskretnie pomijane w żądaniach. Możesz usunąć takie adresy MAC upewniając się, że drugi najmniej istotny element Najważniejszy bajt elementu macAddress to 0, np. 1 bit reprezentowany przez 2 w argumencie 02:00:00:00:00:00. Adres MAC transmisji (FF:FF:FF:FF:FF:FF) to przykładowy adres MAC, co można by wykluczyć przez ten filtr.

Zakres adresów MAC z zakresu od 00:00:5E:00:00:00 do 00:00:5E:FF:FF:FF to zarezerwowany dla IANA i często używany do zarządzania siecią i funkcji multicast. co wyklucza używanie ich jako sygnału lokalizacyjnego. Usuń te elementy Adresy MAC z danych wejściowych do interfejsu API.

Na przykład adresy MAC używane do geolokalizacji można zebrać z tablica macAddress ciągów o nazwie macs:

Jawa
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 powoduje wyświetlenie tylko 1c:34:56:78:9a:bc . Ponieważ ta lista zawiera mniej niż 2 adresy MAC sieci Wi-Fi, żądanie nie powiedzie się i zostanie wyświetlony kod HTTP 404 (notFound) odpowiedź.

Odpowiedzi dotyczące geolokalizacji

Żądanie geolokalizacji zwraca odpowiedź w formacie JSON który określa lokalizację i promień.

  • location: szacowana szerokość i długość geograficzna użytkownika. współrzędne w stopniach. Zawiera 1 element lat i 1 lng .
  • accuracy: dokładność oszacowanej lokalizacji w metrach. Reprezentuje promień okręgu wokół podanego location
{
  "location": {
    "lat": 37.421875199999995,
    "lng": -122.0851173
  },
  "accuracy": 120
}