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 parâmetro key. O key é a chave de API do aplicativo. Essa chave identifica o 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 são opcionais, salvo indicação em contrário:

Campo Tipo de JSON Descrição Observações
homeMobileCountryCode number (uint32) O código de país para dispositivos móveis (MCC) da rede casa do dispositivo. Compatível com radioType gsm (padrão), wcdma, lte e nr. Não é usado para cdma.
Intervalo válido: de 0 a 999.
homeMobileNetworkCode number (uint32) O código de rede móvel da rede home do dispositivo. Esse é o MNC de GSM, WCDMA, LTE e NR.
CDMA usa o ID do sistema (SID, na sigla em inglês).
Intervalo válido para MNC: 0 a 999.
Intervalo válido para SID: 0 a 32767.
radioType string o tipo de rádio móvel. Os valores aceitos são gsm, cdma, wcdma, lte e nr. Embora esse campo seja opcional, ele precisa ser sempre incluído se o tipo de opção for conhecido pelo cliente.
Se o campo for omitido, a API Geolocation assumirá como padrão gsm, o que vai gerar resultados inválidos ou nenhum resultado se o tipo de rádio presumido estiver incorreto.
carrier string o nome da operadora.
considerIp boolean Especifica se é necessário usar a geolocalização por IP se sinais de Wi-Fi e de torre de celular estiverem ausentes, vazios ou não forem suficientes para estimar a localização do dispositivo. O valor padrão é true. Defina considerIp como false para evitar substituição.
cellTowers array uma matriz de objetos de torre de celular. Consulte a seção Objetos de torre de celular abaixo.
wifiAccessPoints array uma matriz de objetos de ponto de acesso Wi-Fi. Consulte a seção Objetos de ponto de acesso Wi-Fi abaixo.

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

Campo Tipo de JSON Descrição Observações
cellId number (uint32) identificador exclusivo do celular. Obrigatório para radioType gsm (padrão), cdma, wcdma e lte, rejeitado para nr.
Consulte a seção Calculando o ID de celular abaixo, que também lista os intervalos de valores válidos para cada tipo de opção.
newRadioCellId number (uint64) Identificador exclusivo da célula NR (5G). Obrigatório para radioType nr; rejeitado para outros tipos.
Consulte a seção Como calcular o newRadioCellId abaixo, que também lista o intervalo de valores válido para o campo.
locationAreaCode number (uint32) O código de área de localização (LAC) para redes GSM e WCDMA.
O ID de rede (NID, na sigla em inglês) para redes CDMA.
O código de área de rastreamento (TAC, na sigla em inglês) para redes LTE e NR.
Obrigatório para radioType gsm (padrão) e cdma, opcional para outros valores.
Intervalo válido com gsm, cdma, wcdma e lte: 0–65535.
Intervalo válido com nr: 0–16777215.
mobileCountryCode number (uint32) O código de país móvel (MCC) da torre de celular. Obrigatório para radioType gsm (padrão), wcdma, lte e nr. Não é usado para cdma.
Intervalo válido: de 0 a 999.
mobileNetworkCode number (uint32) O código de rede móvel da torre de celular. Esse é o MNC de GSM, WCDMA, LTE e NR.
CDMA usa o ID do sistema (SID, na sigla em inglês).
Obrigatório.
Intervalo válido para MNC: 0 a 999.
Intervalo válido para SID: 0 a 32767.

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

Campo Tipo de JSON Descrição Observações
age number (uint32) o número de milissegundos desde que o celular era primário. Se a idade for 0, cellId ou newRadioCellId representará uma medida atual.
signalStrength number (double) a força do sinal de rádio medida em dBm.
timingAdvance number (double) O valor de avanço de tempo.

Calculando cellId

Os tipos de rádio anteriores ao 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 de estação base (BID) no estado em que se encontra. Intervalo válido: 0–65535.
  • As redes WCDMA (3G) usam a identidade de celular UTRAN/GERAN (UC-ID), que é um valor inteiro de 28 bits que concatena o identificador do controlador de rede de rádio de 12 bits (RNC-ID, na sigla em inglês) 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–268435455.
    Observação:especificar apenas o valor do ID de celular de 16 bits em redes WCDMA resulta em resultados incorretos ou em zero.
  • 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 de 20 bits (eNBId) e o ID de célula (CID) de 8 bits.
    Fórmula: enb_id << 8 | cid.
    Intervalo válido: 0–268435455.
    Observação:especificar apenas o valor de ID de celular de 8 bits em redes LTE resulta em resultados incorretos ou em zero.

Colocar valores fora desses intervalos na solicitação da API pode resultar em comportamento indefinido. A critério do Google, a API 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.

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élula 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 New Radio Cell Identity (NCI) de 36 bits no estado em que se encontra.
    Intervalo válido: 0 a 68719476735.

Confira 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, e todos os outros campos são opcionais.

Campo Tipo de JSON Descrição Observações
macAddress string O endereço MAC do nó Wi-Fi. Ele é normalmente chamado de BSS, BSSID ou endereço MAC. Obrigatório.String hexadecimal separada por dois pontos (:).
Somente endereços MAC administrados universalmente podem ser localizados pela API. Outros endereços MAC são descartados silenciosamente e podem fazer com que uma solicitação de API fique efetivamente vazia. Para ver mais detalhes, consulte Como descartar pontos de acesso Wi-Fi inúteis.
signalStrength number (double) a intensidade atual do sinal medida em dBm. Para pontos de acesso Wi-Fi, os valores de dBm costumam ser -35 ou menos e variam de -128 a -10 dBm. Não se esqueça de incluir o sinal de menos.
age number (uint32) o número de milissegundos desde que o ponto de acesso foi detectado.
channel number (uint32) o canal pelo qual o cliente se comunica com o ponto de acesso.
signalToNoiseRatio number (double) A proporção atual sinal para ruído medida em dB.

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

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

Exemplos de solicitação

Para 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": "94:b4:0f:fd:c1:40",
      "signalStrength": -35,
      "signalToNoiseRatio": 0
    }
  ]
}

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

{
  "location": {
      "lat": 37.4241876,
      "lng": -122.0917381
  },
  "accuracy": 32.839
}

Descarte de 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 êxito 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, mitigações como o uso de sinais de local 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 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.

Endereços MAC administrados localmente não são sinais de localização úteis para a API e são descartados silenciosamente das solicitações. Você pode remover esses endereços MAC garantindo que o segundo bit menos significativo do byte mais significativo de 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 endereço MAC que seria excluído de maneira ú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 IANA e muitas vezes é usado para gerenciamento de rede e funções multicast, o que impede o uso como sinal de localização. Você também precisa remover esses endereços MAC das entradas para a API.

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

O uso desse filtro faz com que apenas 1c:34:56:78:9a:bc permaneça na lista. Como essa lista tem menos de dois endereços MAC 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 pelo usuário, em graus. Contém um lat e um subcampo 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
}