Solicitação e resposta de geolocalização

Solicitações de geolocalização

Solicitações de geolocalização são enviadas usando POST para o seguinte URL:

https://www.googleapis.com/geolocation/v1/geolocate?key=YOUR_API_KEY

É necessário especificar uma chave na solicitação, incluída como o valor de um key parâmetro. Uma key é a chave de API do seu aplicativo. Essa chave identifica seu aplicativo para fins de gerenciamento de cota gerenciamento. Saiba como conseguir uma chave.

Corpo da solicitação

O corpo da solicitação deve ter formatação JSON. Se o corpo da solicitação não for incluído, os resultados serão retornados com base no endereço IP do local da solicitação. Os campos a seguir são aceitos, e todos são opcionais, a menos que indicado de outra forma:

Um exemplo de corpo de solicitação de API Geolocation é mostrado abaixo.

{
  "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.
  ]
}

Objetos de torre de celular

A matriz cellTowers do corpo da solicitação contém zero ou mais objetos de torre de celular.

Os campos opcionais a seguir não são usados, mas podem ser incluídos se os valores estiverem disponíveis.

Como calcular o cellId

Os tipos de rádio anteriores ao NR (5G) usam o campo cellId de 32 bits para transmitir o ID da célula de rede à API Geolocation.

• As redes GSM (2G) usam o ID de célula (CID, na sigla em inglês) de 16 bits como está. Intervalo válido: 0 a 65535.
• As redes CDMA (2G) usam o ID da estação base (BID, na sigla em inglês) de 16 bits como está. Intervalo válido: 0 a 65535.
• As redes WCDMA (3G) usam a identidade de célula UTRAN/GERAN (UC-ID, na sigla em inglês), que é um valor inteiro de 28 bits que concatena o identificador de controlador de rede de rádio (RNC-ID, na sigla em inglês) de 12 bits e o ID de célula (CID, na sigla em inglês) de 16 bits .
  Fórmula: rnc_id << 16 | cid.
  Intervalo válido: 0 a 268435455.
  Observação: especificar apenas o valor de ID de célula de 16 bits em redes WCDMA resulta em resultados incorretos ou nulos.
• As redes LTE (4G) usam a identidade de célula E-UTRAN (ECI, na sigla em inglês), que é um valor inteiro de 28 bits que concatena o identificador de nó B E-UTRAN (eNBId, na sigla em inglês) de 20 bits e o ID de célula (CID, na sigla em inglês) de 8 bits.
  Fórmula: enb_id << 8 | cid.
  Intervalo válido: 0 a 268435455.
  Observação: especificar apenas o valor de ID de célula de 8 bits em redes LTE resulta em resultados incorretos ou nulos.

A colocação de valores fora desses intervalos na solicitação de API pode resultar em um comportamento indefinido. A API, a critério do Google, pode truncar o número para que ele se ajuste ao intervalo documentado, inferir uma correção para o radioType, ou retornar um resultado NOT_FOUND sem nenhum indicador na resposta.

Um exemplo de objeto de torre de celular LTE, que faz parte do corpo da solicitação, está abaixo.

{
  ...

  "cellTowers": [
    {
      "cellId": 170402199,
      "locationAreaCode": 35632,
      "mobileCountryCode": 310,
      "mobileNetworkCode": 410,
      "age": 0,
      "signalStrength": -60,
      "timingAdvance": 15
    }
  ]
}

A resposta à solicitação anterior é assim:

{
  "location": {
    "lat": 37.7801129,
    "lng": -122.4168229
  },
  "accuracy": 180.052
}

Como calcular o newRadioCellId

Redes mais recentes, cujos IDs de célula são maiores que 32 bits, usam o campo newRadioCellId de 64 bits para transmitir o ID da célula de rede à API Geolocation.

• As redes NR (5G) usam a identidade de célula de rádio nova (NCI, na sigla em inglês) de 36 bits no estado em que se encontra.
  Intervalo válido: 0 a 68719476735.

Um exemplo de objeto de torre de celular NR, que faz parte do corpo da solicitação, está abaixo.

{
  ...

  "cellTowers": [
    {
      "newRadioCellId": 68719476735,
      "mobileCountryCode": 310,
      "mobileNetworkCode": 410,
      "age": 0,
      "signalStrength": -60,
    }
  ]
}

A resposta à solicitação anterior é assim:

{
  "location": {
    "lat": 37.7646157,
    "lng": -122.4127361
  },
  "accuracy": 1458.5570522410717
}

Objetos de ponto de acesso Wi-Fi

A matriz wifiAccessPoints do corpo da solicitação precisa conter dois ou mais objetos de ponto de acesso Wi-Fi que representam dispositivos de ponto de acesso estacionários fisicamente distintos. O campo macAddress é obrigatório. Todos os outros campos são opcionais. O serviço ignora pontos de acesso que se movem, como os de aviões e trens.

Um exemplo de objeto de ponto de acesso Wi-Fi, que faz parte do corpo da solicitação, é mostrado abaixo.

{
  ...
  
  "macAddress": "f0:d5:bf:fd:12:ae",
  "signalStrength": -43,
  "signalToNoiseRatio": 0,
  "channel": 11,
  "age": 0
}

A resposta à solicitação anterior é assim:

{
  "location": {
    "lat": 37.7801129,
    "lng": -122.4168229
  },
  "accuracy": 180.052
}

Exemplos de solicitação

Se você quiser testar a API Geolocation com dados de amostra, salve o JSON a seguir em um arquivo:

{
  "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
    }
  ]
}

Em seguida, use curl para fazer sua solicitação na linha de comando:

$ curl -d @your_filename.json -H "Content-Type: application/json" -i "https://www.googleapis.com/geolocation/v1/geolocate?key=YOUR_API_KEY"

A resposta aos endereços MAC anteriores é assim:

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

Como descartar pontos de acesso Wi-Fi não utilizados

A remoção de objetos de ponto de acesso Wi-Fi com macAddresses que são um endereço de transmissão (FF:FF:FF:FF:FF:FF) ou reservados pela IANA pode melhorar a taxa de sucesso das chamadas da API Geolocation que usam o Wi-Fi como entrada. Se, após a filtragem, for possível determinar que uma chamada de API Geolocation não será bem-sucedida, mitigações como o uso de sinais de localização mais antigos ou APs Wi-Fi com sinais mais fracos poderão ser usadas. Essa abordagem é uma compensação entre a necessidade do aplicativo de uma estimativa de localização e os requisitos de precisão e recall. As técnicas de filtragem a seguir demonstram como filtrar as entradas, mas não mostram as mitigações que você, como engenheiro de aplicativos, pode escolher aplicar.

O intervalo de endereços MAC entre 00:00:5E:00:00:00 e 00:00:5E:FF:FF:FF é reservado para a IANA e geralmente usado para gerenciamento de rede e funções de multicast, impedindo o uso como um sinal de localização. Você também precisa remover esses endereços MAC das entradas da API.

Por exemplo, endereços MAC utilizáveis para geolocalização podem ser coletados de um array de macAddress strings chamado macs:

String[] macs = {"ff:ff:ff:ff:ff:ff", "1c:34:56:78:9a:bc", "00:00:5e:00:00:01"};
ArrayList<String> _macs = new ArrayList<>(Arrays.asList(macs));
_macs.removeIf(m -> !(!m.toUpperCase().equals("FF:FF:FF:FF:FF:FF")
                      && !m.substring(0, 8).toUpperCase().equals("00:00:5E")));
    

macs = ['ff:ff:ff:ff:ff:ff', '1c:34:56:78:9a:bc', '00:00:5e:00:00:01']
macs = [m for m in macs if (m.upper() != "FF:FF:FF:FF:FF:FF" and m[:8].upper() != '00:00:5E')]
    

macs = ['ff:ff:ff:ff:ff:ff', '1c:34:56:78:9a:bc', '00:00:5e:00:00:01'];
macs = macs.filter(m => m.toUpperCase() !== "FF:FF:FF:FF:FF:FF"
                        && m.substr(0, 8).toUpperCase() !== '00:00:5E');
    

O uso desse filtro resulta apenas em 1c:34:56:78:9a:bc restante na lista. Como essa lista tem menos de dois endereços MAC de Wi-Fi, a solicitação não seria bem-sucedida e uma resposta HTTP 404 (notFound) seria retornada.

Respostas de geolocalização

Uma solicitação de geolocalização bem-sucedida retorna uma resposta formatada em JSON que define um local e um raio.

• location: as coordenadas de latitude e longitude estimadas do usuário, em graus. Contém um lat e um lng subcampo.
• accuracy: a precisão do local aproximado, em metros. Isso representa o raio de um círculo ao redor do fornecido location.

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

A API retorna um local e um raio de precisão com base nos sinais de entrada. Embora a API possa retornar um local altamente preciso, a precisão pode variar dependendo da origem, do número, da densidade e da intensidade dos sinais disponíveis. Normalmente, você pode esperar os seguintes raios de precisão:

• Pontos de acesso Wi-Fi: se a solicitação incluir dois ou mais wifiAccessPoints, o raio de precisão retornado será normalmente de cerca de 20 metros. A precisão melhora com o número de pontos de acesso e sinais mais fortes (medidos em dBm), com intensidades de sinal que geralmente variam de -100 a -20 dBm.
• Torres de celular: se as informações de Wi-Fi não estiverem disponíveis ou forem insuficientes, a API usará cellTowers para localização. A precisão varia significativamente com o tipo de torre de celular, a intensidade do sinal e a densidade da rede:
  • Macrocélulas (o tipo mais comum, usado para cobertura de área ampla ) oferecem menor precisão. O raio geralmente está na faixa de centenas de metros e pode chegar a vários milhares de metros em áreas com cobertura de torre de celular esparsa. Para macrocélulas, é incomum alcançar um raio de precisão abaixo de 100 metros. A acurácia geralmente é maior para torres de celular com sinais fortes. Sinais fortes são normalmente > -110 dBm para LTE (intervalo de sinal -140 a -55 dBm), > -100 dBm para WCDMA (intervalo de sinal -111 a -53 dBm), > -100 dBm para CDMA (intervalo de sinal -120 a -40 dBm) e > -80 dBm para GSM (intervalo de sinal -121 a -1 dBm).
  • Células pequenas (por exemplo, femtocélulas, picocélulas ou repetidores internos) fornecem a localização mais precisa com base em células, com raios de precisão que podem estar na faixa de 10 a 30 metros.
• Geolocalização de IP: se considerIp for true e nenhum sinal de Wi-Fi ou torre de celular puder ser geolocalizado, a API estimará a localização com base no endereço IP da solicitação. Esse método oferece a menor precisão, com raios que podem ser de milhares de metros. Consulte Por que o raio de precisão é muito grande? no guia de solução de problemas.