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

É preciso especificar uma chave na solicitação, incluída como o valor de um parâmetro key. O key é a chave de API do aplicativo. Essa chave identifica seu aplicativo para fins de gerenciamento de cotas. Saiba como receber uma chave.

Corpo da solicitação

O corpo da solicitação deve ter formatação JSON. Se o corpo da solicitação não estiver 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 os campos são opcionais, a menos que especificado de outra forma:

Veja abaixo um exemplo de corpo de solicitação da API Geolocation.

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

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 poderão ser incluídos se os valores estiverem disponíveis.

Calculando cellId

Os tipos de rádio anteriores à NR (5G) usam o campo cellId de 32 bits para transmitir o Cell-ID da rede para a API Geolocation.

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

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

Confira abaixo um exemplo de objeto de torre de celular LTE.

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

Calculando newRadioCellId

As redes mais recentes com IDs de células maiores que 32 bits usam o campo newRadioCellId de 64 bits para transmitir o ID de célula da rede para a API Geolocation.

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

Veja abaixo um exemplo de objeto de torre de celular NR.

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

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. macAddress é obrigatório. Todos os outros campos são opcionais.

Veja abaixo um exemplo de objeto de ponto de acesso Wi-Fi.

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

Exemplos de solicitação

Se você quiser testar a API Geolocation com dados de amostra, salve o seguinte JSON 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
    }
  ]
}

Você pode usar cURL para fazer sua solicitação pela 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 dos endereços MAC anteriores é semelhante a esta:

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

Descartando pontos de acesso Wi-Fi não utilizados

A remoção de objetos de ponto de acesso Wi-Fi com macAddresses que são administrados localmente pode melhorar a taxa de sucesso das chamadas da API Geolocation que usam Wi-Fi como entrada. Se, após a filtragem, for determinado que uma chamada da API Geolocation não terá sucesso, será possível usar mitigações como o uso de sinais de localização mais antigos ou APs Wi-Fi com sinais mais fracos. Essa abordagem é um equilíbrio entre a necessidade do aplicativo de uma estimativa de local 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 aplicativo, pode optar por aplicar.

Os endereços MAC administrados localmente não são indicadores de localização úteis para a API e são silenciosamente descartados das solicitações. É possível remover esses endereços MAC garantindo que o segundo bit menos significativo do byte mais significativo do macAddress seja 0, por exemplo, o 1 bit representado pelo 2 em 02:00:00:00:00:00. O endereço MAC de transmissão (FF:FF:FF:FF:FF:FF) é um exemplo de um endereço MAC que seria útil por esse filtro.

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 multicast, o que impede o uso como um sinal de local. Remova também esses endereços MAC das entradas para a API.

Por exemplo, endereços MAC utilizáveis para geolocalização podem ser coletados de uma matriz de strings macAddress chamada 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');
    

O uso desse filtro resulta apenas no 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 será bem-sucedida e uma resposta HTTP 404 (notFound) será 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: coordenadas estimadas de latitude e longitude do usuário em graus. Contém um subcampo lat e um lng.
• accuracy: a precisão da localização estimada, em metros. Isso representa o raio de um círculo em torno do location especificado.

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