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:

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) 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.

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:

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