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 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:

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.

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

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) w postaci domyślnej. Dopuszczalny zakres: 0–65535.
• 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).
  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).
  Wzór: 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.

Umieszczenie 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ć 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.

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 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ć 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
}

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

Usunięcie obiektów punktu dostępu Wi-Fi z identyfikatorami macAddress, które są locally-administered, 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 przefiltrowaniu 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 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 do rozgłoszenia (FF:FF:FF:FF:FF:FF) to przykład adresu MAC, który zostanie wykluczony 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 znaków macAddress o nazwie macs:

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")));
    

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')]
    

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 powoduje, że na liście pozostają 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 szerokości i długości geograficznej użytkownika w stopniach. Zawiera 1 pole 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
}