Ta strona została przetłumaczona przez Cloud Translation API.

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 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 są opcjonalne, o ile nie podano inaczej):

Pole	Typ JSON	Opis	Uwagi
`homeMobileCountryCode`	`number` (`uint32`)	Kod 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 sieci komórkowej sieci domowej urządzenia. Jest to kod MNC dla sieci GSM, WCDMA, LTE i NR. CDMA używa identyfikatora systemu (SID).	Dozwolony zakres dla 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 typ radia jest znany klientowi. Jeśli to pole zostanie pominięte, interfejs Geolocation API przyjmie domyślnie wartość `gsm`, co spowoduje zwrócenie nieprawidłowych lub zerowych wyników, jeśli założony typ radia jest nieprawidłowy.
`carrier`	`string`	Nazwa przewoźnika.
`considerIp`	`boolean`	Określa, czy w przypadku braku sygnałów Wi-Fi i stacji bazowych, ich pustych wartości lub niewystarczających danych do oszacowania lokalizacji urządzenia należy użyć geolokalizacji IP.	Domyślna wartość to `true`. Ustaw wartość `considerIp` na `false`, aby zapobiec powrotowi do poprzedniej wersji.
`cellTowers`	`array`	Tablica obiektów stacji bazowych.	Zapoznaj się z sekcją Obiekty stacji bazowych poniżej.
`wifiAccessPoints`	`array`	Tablica obiektów punktów dostępu Wi-Fi.	Więcej informacji znajdziesz w sekcji Obiekty punktów dostępu Wi-Fi poniżej.

Poniżej znajduje się przykładowy tekst żądania 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 zero lub więcej obiektów stacji bazowych.

Pole	Typ 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`. W sekcji Obliczanie identyfikatora komórki poniżej znajdziesz też listę zakresów prawidłowych wartości dla każdego typu radia.
`newRadioCellId`	`number` (`uint64`)	Unikalny identyfikator komórki NR (5G).	Wymagany w przypadku `radioType` `nr`; odrzucony w przypadku innych typów. Więcej informacji znajdziesz w sekcji Obliczanie wartości newRadioCellId poniżej. Znajduje się tam też lista prawidłowych zakresów wartości tego pola.
`locationAreaCode`	`number` (`uint32`)	Kod obszaru lokalizacji (LAC) dla sieci GSM i WCDMA. Identyfikator sieci (NID) w przypadku sieci CDMA. Kod obszaru śledzenia (TAC) dla sieci LTE i NR.	Wymagany w przypadku wartości `radioType` `gsm` (domyślna) 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 `nr`: 0–16777215.
`mobileCountryCode`	`number` (`uint32`)	Kod MCC (Mobile Country Code) wieży komórkowej.	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 sieci komórkowej stacji bazowej. Jest to kod MNC dla sieci GSM, WCDMA, LTE i NR. CDMA używa identyfikatora systemu (SID).	Wymagane. Prawidłowy zakres dla MNC: 0–999. Prawidłowy zakres identyfikatora SID: 0–32767.

Te pola opcjonalne nie są używane, ale można je uwzględnić, jeśli są dostępne wartości.

Pole	Typ JSON	Opis	Uwagi
`age`	`number` (`uint32`)	Liczba milisekund od momentu, gdy ta komórka stała się podstawową.	Jeśli wiek 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`

W przypadku typów radiowych starszych niż NR (5G) do przekazywania identyfikatora komórki sieci do interfejsu Geolocation API używane jest 32-bitowe pole cellId.

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 w sieciach WCDMA tylko 16-bitowej wartości identyfikatora komórki powoduje uzyskanie nieprawidłowych lub zerowych wyników.
Sieci LTE (4G) używają identyfikatora komórki E-UTRAN (ECI), który jest 28-bitową liczbą całkowitą łączącą 20-bitowy identyfikator węzła E-UTRAN B (eNBId) i 8-bitowy identyfikator komórki (CID).
Formuła: enb_id << 8 | cid.
Prawidłowy zakres: 0–268435455.
Uwaga: podanie w sieciach LTE tylko 8-bitowej wartości identyfikatora komórki powoduje uzyskanie nieprawidłowych lub zerowych wyników.

Umieszczenie w żądaniu API wartości spoza tych zakresów może spowodować nieokreślone działanie. Interfejs API może według uznania Google skrócić liczbę, aby zmieściła się w udokumentowanym zakresie, wywnioskować korektę wartości 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
}

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-bitowego identyfikatora komórki New Radio (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 powyższe żą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ę go BSS, BSSID lub adresem MAC.	Wymagany. Ciąg szesnastkowy rozdzielony dwukropkami (`:`). Tylko uniwersalne adresy MAC można lokalizować za pomocą interfejsu API. Inne adresy MAC są cicho odrzucane, co może spowodować, że żądanie do interfejsu API stanie się puste. Szczegółowe informacje znajdziesz w artykule Usuwanie nieużywanych punktów dostępu Wi-Fi.
`signalStrength`	`number` (`double`)	Obecna 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 o znaku 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ł, za pomocą którego klient komunikuje się z punktem dostępu.
`signalToNoiseRatio`	`number` (`double`)	Aktualny 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ć interfejs Geolocation API z przykładowymi danymi, zapisz poniższy 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ć polecenia curl, aby wysł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 następująco:

{
  "location": {
    "lat": 37.4241173,
    "lng": -122.0915717
  },
  "accuracy": 20
}

Usuwanie nieużywanych punktów dostępu WiFi

Usunięcie obiektów punktów dostępu WiFi zawierających macAddress, które są administrowane lokalnie, może zwiększyć wskaźnik powodzenia wywołań interfejsu API geolokalizacji wykorzystujących WiFi jako dane wejściowe. Jeśli po przefiltrowaniu okaże się, że wywołanie interfejsu API geolokalizacji nie powiedzie się, można zastosować środki zaradcze, takie jak użycie starszych sygnałów lokalizacji lub punktów dostępowych WiFi o słabszym sygnale. To kompromis między potrzebą aplikacji w zakresie szacowania lokalizacji a wymaganiami dotyczącymi precyzji i pełności. Poniższe techniki filtrowania pokazują, jak filtrować dane wejściowe, ale nie przedstawiają środków, które możesz zastosować jako inżynier aplikacji.

Lokalnie administrowane adresy MAC nie są przydatnymi sygnałami lokalizacji dla interfejsu API i są cicho usuwane z żądań. Możesz usunąć takie adresy MAC, upewniając się, że drugi najmniej znaczący bit najbardziej znaczącego bajtu macAddress to 0, np. bit 1 reprezentowany przez 2 w 02:00:00:00:00:00. Adres MAC transmisji (FF:FF:FF:FF:FF:FF) to przykład adresu MAC, który warto wykluczyć za pomocą tego filtra.

Zakres adresów MAC pomiędzy 00:00:5E:00:00:00 i 00:00:5E:FF:FF:FF jest zarezerwowany dla IANA i często używany do zarządzania siecią oraz funkcji multicast, co wyklucza ich wykorzystanie 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 uzyskać z tablicy ciągó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');

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

Odpowiedzi dotyczące geolokalizacji

Pomyślne żądanie geolokalizacji zwraca odpowiedź w formacie JSON, definiującą lokalizację i promień.

location: szacunkowe współrzędne geograficzne użytkownika (szerokość i długość) w stopniach. Zawiera jedno pole lat i jedno pole lng.
accuracy: dokładność szacowanej lokalizacji w metrach. Jest to promień okręgu wokół danego punktu location.

{
  "location": {
    "lat": 37.421875199999995,
    "lng": -122.0851173
  },
  "accuracy": 120
}