Opis

Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

Wprowadzenie

Interfejs Geolocation API zwraca promień i lokalizację oraz zwraca dokładność na podstawie informacji o wieżach komórkowych i węzłach Wi-Fi, które może wykryć klient komórkowy. W tym dokumencie opisano protokół służący do wysyłania tych danych do serwera i zwracania odpowiedzi klientowi.

Komunikacja odbywa się przez protokół HTTPS (POST). Zarówno żądanie, jak i odpowiedź mają format JSON, a typ treści to application/json.

Zanim zaczniesz

Zanim zaczniesz korzystać z interfejsu Geolocation API, sprawdź wymagania dotyczące uwierzytelniania (potrzebujesz klucza interfejsu API) oraz informacje o wykorzystaniu i rozliczeniach interfejsu API (musisz włączyć płatności w projekcie).

Prośby o lokalizację geograficzną

Żą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 określić klucz uwzględniony jako wartość parametru key. key to klucz interfejsu API Twojej aplikacji. Ten klucz identyfikuje 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 zostanie uwzględniona, wyniki zostaną zwrócone na podstawie adresu IP lokalizacji żądania. Poniższe pola są obsługiwane i wszystkie są opcjonalne, chyba że zaznaczono inaczej:

Pole Typ pliku JSON Opis Uwagi
homeMobileCountryCode number (uint32) Kod kraju mobilnego (MCK) sieci mobilnej 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 sieci domowej urządzenia. Jest to MNC dla GSM, WCDMA, LTE i NR.
CDMA korzysta z identyfikatora systemu (SID).
Prawidłowy zakres dla MNC: 0–999.
Prawidłowy zakres dla identyfikatora SID: 0–32767.
radioType string Typ radia na urządzeniu mobilnym. Obsługiwane wartości to gsm, cdma, wcdma, lte i nr. To pole jest opcjonalne, ale należy je uwzględnić, jeśli typ radia jest znany klientowi.
Jeśli pominiesz to pole, interfejs Geolocation API otrzyma domyślną wartość gsm, która będzie skutkować nieprawidłowymi lub zerowymi wynikami, jeśli zakładany typ radia będzie nieprawidłowy.
carrier string Nazwa operatora.
considerIp boolean Określa, czy należy przywrócić geolokalizację adresu IP, jeśli brak sygnałów Wi-Fi oraz stacji bazowych sieci komórkowej, są one puste lub nie wystarczają do oszacowania lokalizacji urządzenia. Domyślna wartość to true. Aby wyłączyć funkcję zastępczą, ustaw considerIp na false.
cellTowers array Tablica obiektów wieży wieży. Zobacz sekcję Obiekty w stacji bazowej 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ładową treść żą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 w stacji bazowej

Tablica cellTowers w treści żądania zawiera zero lub więcej obiektów wieży wieży.

Pole Typ pliku JSON Opis Uwagi
cellId number (uint32) Unikalny identyfikator komórki. Wymagane dla: radioType gsm (domyślnie), cdma, wcdma i lte; odrzucone dla nr.
Zapoznaj się z sekcją Obliczanie komórki id, która zawiera też prawidłowe zakresy wartości dla poszczególnych typów radia.
newRadioCellId number (uint64) Unikalny identyfikator komórki NR (5G). Wymagany w przypadku radioType nr; odrzucony w przypadku innych typów.
Poniżej znajdziesz sekcję Obliczanie nowego parametru RadioCell, w której znajdziesz też prawidłowy zakres wartości dla tego pola.
locationAreaCode number (uint32) Kod lokalizacji (LAC) w sieciach GSM i WCDMA.
Identyfikator sieci (NID) sieci CDMA.
Kod śledzenia (TAC) dla sieci LTE i NR.
Wymagany w przypadku radioType gsm (domyślny) i cdma, opcjonalny w przypadku innych wartości.
Ważny zakres w polach gsm, cdma, wcdma i lte: 0–65 535.
Prawidłowy zakres w polu nr: 0–16777215.
mobileCountryCode number (uint32) Numer mobilny (MCK) stacji bazowej sieci komórkowej. Wymagane dla: 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 sieci komórkowej. Jest 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 identyfikatora SID: 0–32767.

Poniższe opcjonalne pola nie są obecnie używane, ale mogą zostać uwzględnione, jeśli wartości są dostępne.

Pole Typ pliku JSON Opis Uwagi
age number (uint32) Liczba milisekund od ostatniej komórki. Jeśli wiek wynosi 0, pole cellId lub newRadioCellId odpowiada bieżącemu pomiarowi.
signalStrength number (double) Siła sygnału radiowego mierzona w dBm.
timingAdvance number (double) Wartość przepływu czasu.

Obliczam: cellId

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

  • Sieci GSM (2G) używają tego samego 16-bitowego identyfikatora komórki (CID). Prawidłowy zakres: 0–65 535.
  • 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 – 28-bitowej wartości całkowitej łączącej 12-bitowy identyfikator sieci radiowej (RNC-ID) i 16-bitowy identyfikator komórki (CID).
    Formuła: rnc_id << 16 | cid.
    Prawidłowy zakres: 0–268435455.
    Uwaga: określenie tylko 16-bitowej wartości identyfikatora komórki w sieciach WCDMA spowoduje wygenerowanie nieprawidłowych lub braku wyników.
  • Sieci LTE (4G) korzystają z E-UTRAN Cell Identity (ECI), która jest 28-bitową liczbą całkowitą łączącą 20-bitowy identyfikator węzła E-UTRAN (eNBID) i 8-bitowy identyfikator komórki (CID).
    Formuła: enb_id << 8 | cid.
    Prawidłowy zakres: 0–268435455.
    Uwaga: określenie tylko 8-bitowej wartości identyfikatora komórki w sieciach LTE spowoduje nieprawidłowe lub zerowe wyniki.

Umieszczenie wartości poza tymi zakresami w żądaniu API może spowodować nieokreślone zachowanie. Google może według własnego uznania skrócić liczbę tak, aby mieściła się w zakresie udokumentowanym, stała się poprawką radioType lub zwróciła wynik NOT_FOUND bez wskaźnika.

Poniżej znajdziesz przykładowy obiekt wieży 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, wykorzystują pole 64-bitowe newRadioCellId do przekazywania identyfikatora sieci sieciowej do interfejsu Geolocation API.

  • Sieci NR (5G) używają 36-bitowego protokołu NCI (New Radio Identity Identity).
    Prawidłowy zakres: 0–68719476735.

Poniżej znajdziesz przykładowy obiekt wieży NR komórki.

{
  "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 punktów dostępu Wi-Fi. 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. Nazywa się go zwykle adresem BSS, BSSID lub MAC. Wymagane. : (dwukropkowy) ciąg znaków w formacie szesnastkowym.
signalStrength number (double) Bieżąca siła sygnału mierzona w dBm. W przypadku punktów dostępu Wi-Fi wartości to zwykle -35 lub niższe i od -128 do -10 dBm. Pamiętaj, aby uwzględnić znak minusa.
age number (uint32) Liczba milisekund od wykrycia tego punktu dostępu.
channel number (uint32) Kanał, z którym klient komunikuje się z punktem dostępu.
signalToNoiseRatio number (double) bieżący sygnał do hałasu mierzony w dB.

Przykładowy obiekt punktu dostępu Wi-Fi znajdziesz poniżej.

{
  "macAddress": "9c:1c:12:b0:45:f1",
  "signalStrength": -43,
  "signalToNoiseRatio": 0,
  "channel": 11,
  "age": 0
}

Odpowiedzi geolokalizacyjne

Żądanie geolokalizacji zwróci odpowiedź w formacie JSON definiującą lokalizację i promień.

  • location: szacowana i długa długość geograficzna użytkownika w stopniach. Zawiera jedno pole lat i jedno pole lng.
  • accuracy: dokładność przybliżonej lokalizacji w metrach. Jest to promień okręgu wokół podanego location.
{
  "location": {
    "lat": 37.421875199999995,
    "lng": -122.0851173
  },
  "accuracy": 120
}

Błędy

W przypadku błędu zwracana jest standardowa odpowiedź w postaci błędu, a kod stanu HTTP jest ustawiany na stan błędu.

Odpowiedź zawiera obiekt z pojedynczym obiektem error z tymi kluczami:

  • code: jest taki sam jak stan HTTP odpowiedzi.
  • message: krótki opis błędu.
  • errors: lista błędów, które wystąpiły. Każdy błąd zawiera identyfikator typu błędu (reason) i krótki opis (message).

Na przykład wysłanie nieprawidłowego pliku JSON spowoduje taki błąd:

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "parseError",
    "message": "Parse Error",
   }
  ],
  "code": 400,
  "message": "Parse Error"
 }
}

Możliwe błędy:

Uzasadnienie Domena Kod stanu HTTP Opis
dailyLimitExceeded usageLimits 403 Przekroczono limit dzienny.
keyInvalid usageLimits 400 Twój klucz interfejsu API jest nieprawidłowy dla interfejsu Geolocation API. Sprawdź, czy został przez Ciebie uwzględniony cały klucz oraz że został przez Ciebie kupiony interfejs API, możesz też włączyć płatności i aktywować go, aby uzyskać limit bez opłat.
userRateLimitExceeded usageLimits 403 Przekroczono limit żądań skonfigurowany w Google Cloud Console. Ten limit jest zwykle określany jako żądania na dzień, żądania na 100 sekund i żądania na 100 sekund na użytkownika. Ten limit należy skonfigurować w taki sposób, aby pojedynczy limit użytkowników lub grupy użytkowników nie wyczerpywał się, a jednocześnie umożliwić im uzyskanie rozsądnego dostępu. Informacje o konfigurowaniu tych limitów znajdziesz w artykule Ograniczanie wykorzystania interfejsu API.
notFound geolocation 404 Żądanie było prawidłowe, ale nie zostały zwrócone żadne wyniki.
parseError global 400 Treść żądania nie jest prawidłowym plikiem JSON. Szczegółowe informacje o poszczególnych polach znajdziesz w sekcji Treść żądania.

Przykładowe żądania

Jeśli chcesz wypróbować interfejs Geolocation API z przykładowymi danymi, zapisz w pliku ten plik JSON:

{
  "considerIp": "false",
  "wifiAccessPoints": [
    {
      "macAddress": "84:d4:7e:f6:99:64",
      "signalStrength": -54,
      "signalToNoiseRatio": 0
    },
    {
      "macAddress": "84:d4:7e:f6:99:71",
      "signalStrength": -43,
      "signalToNoiseRatio": 0
    },
    {
      "macAddress": "84:d4:7e:f7:21:35",
      "signalStrength": -32,
      "signalToNoiseRatio": 0
    }
  ]
}

Następnie możesz użyć cURL do wysłania żądania 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 macOS wygląda tak:

{
  "location": {
      "lat": 37.4237423,
      "lng": -122.0915814
  },
  "accuracy": 20
}

Jeśli nie masz klucza interfejsu API, zapoznaj się z artykułem Pobieranie klucza interfejsu API.

Aby uzyskać dodatkowe dane, zbieraj informacje z urządzenia z Androidem za pomocą pakietu SDK Miejsc na Androida i interfejsów API lokalizacji dla Androida oraz z urządzenia z iOS za pomocą pakietu SDK Miejsc na iOS.

Najczęstsze pytania

Dlaczego w odpowiedzi geolokalizacyjnej znajduje się bardzo duży promień accuracy?

Jeśli w polu accuracy Twoja odpowiedź geolokalizacyjna zawiera bardzo dużą wartość, usługa może ustalać geolokalizację na podstawie adresu IP żądania, a nie punktów Wifi czy stacji bazowych sieci komórkowej. Może się tak zdarzyć, jeśli żadne stacje bazowe lub punkty dostępu nie są prawidłowe lub rozpoznawane.

Aby potwierdzić, że jest to problem, ustaw w żądaniu considerIp wartość false. Jeśli odpowiedzią jest 404, masz pewność, że obiektów wifiAccessPoints i cellTowers nie udało się ustawić geolokalizacji.