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. key é a chave de API do seu aplicativo. Essa chave identifica seu aplicativo para fins de gerenciamento de cotas. 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 compatíveis, e todos são opcionais, a menos que indicado de outra forma:

Campo Tipo de JSON Descrição Observações
homeMobileCountryCode number (uint32) O código de país para dispositivos móveis (MCC) da rede doméstica do dispositivo. Compatível com radioType gsm (padrão), wcdma, lte e nr; não usado para cdma.
Intervalo válido: 0–999.
homeMobileNetworkCode number (uint32) O código de rede móvel da rede doméstica do dispositivo. Este é o MNC para GSM, WCDMA, LTE e NR.
O CDMA usa o ID do sistema (SID).		 Intervalo válido para MNC: 0–999.
Intervalo válido para SID: 0–32767.
radioType string o tipo de rádio móvel. Os valores compatíveis são gsm, cdma, wcdma, lte e nr. Embora esse campo seja opcional, ele precisa ser incluído se o tipo de rádio for conhecido pelo cliente.
Se o campo for omitido, a API Geolocation usará gsm como padrão, o que vai resultar em resultados inválidos ou zero se o tipo de rádio assumido estiver incorreto.
carrier string o nome da operadora.
considerIp boolean Especifica se a geolocalização de IP deve ser usada como alternativa se os sinais de Wi-Fi e de torres 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 o fallback.
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.

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

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

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 Como calcular cellId abaixo, que também lista os intervalos de valores válidos para cada tipo de rádio.
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álidos para o campo.
locationAreaCode number (uint32) O código de área de localização (LAC, na sigla em inglês) para redes GSM e WCDMA.
O ID de rede (NID) 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 para dispositivos móveis (MCC) da torre de celular. Obrigatório para radioType gsm (padrão), wcdma, lte e nr. Não usado para cdma.
Intervalo válido: 0–999.
mobileNetworkCode number (uint32) O código de rede móvel da torre de celular. Este é o MNC para GSM, WCDMA, LTE e NR.
O CDMA usa o ID do sistema (SID).		 Obrigatório.
Intervalo válido para MNC: 0–999.
Intervalo válido para SID: 0–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 representa uma medição 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 ID da célula de rede à API Geolocation.

  • As redes GSM (2G) usam o ID de célula (CID) de 16 bits como está. Intervalo válido: 0 a 65535.
  • As redes CDMA (2G) usam o ID da estação de 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), que é um valor inteiro de 28 bits que concatena o identificador de 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–268435455.
    Observação:especificar apenas o valor do 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–268435455.
    Observação:especificar apenas o valor do ID de célula de 8 bits em redes LTE resulta em resultados incorretos ou nulos.

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

Veja abaixo um exemplo de objeto de torre de celular LTE, que faz parte do corpo da solicitação.

{
  ...

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

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 de rede à API Geolocation.

  • As redes NR (5G) usam a identidade de célula de rádio novo (NCI, na sigla em inglês) de 36 bits como está.
    Intervalo válido: 0 a 68719476735.

Veja abaixo um exemplo de objeto de torre de celular NR, que faz parte do corpo da solicitação.

{
  ...

  "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 representem 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.

Campo Tipo de JSON Descrição Observações
macAddress string O endereço MAC do nó de Wi-Fi. Normalmente, ele é 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 usando a API. Outros endereços MAC são descartados silenciosamente e podem fazer com que uma solicitação de API fique vazia. Para 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 geralmente são -35 ou menos e variam de -128 a -10 dBm. Não se esqueça de incluir o sinal de menos.
Para valores maiores que -10 dBm, a API retorna NOT FOUND.
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 sinal-ruído atual medida em dB.

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

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

Em seguida, use 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 para os endereços MAC anteriores é assim:

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

Remoção de pontos de acesso Wi-Fi não utilizados

Remover objetos de ponto de acesso Wi-Fi com macAddresss 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 de API Geolocation que usam o Wi-Fi como entrada. Se, após a filtragem, for determinado que uma chamada de API Geolocation não seria bem-sucedida, poderão ser usadas mitigações, como o uso de indicadores de localização mais antigos ou APs de Wi-Fi com indicadores mais fracos. 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 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 funções de gerenciamento de rede e multicast, impedindo o uso como um indicador de local. Também é necessário 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 chamada macs:

Java
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")));
Python
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')]
JavaScript
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 em apenas 1c:34:56:78:9a:bc permanecendo 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 estimadas de latitude e longitude do usuário, em graus. Contém um subcampo lat e um lng.
  • accuracy: a precisão do local aproximado, em metros. Isso representa o raio de um círculo ao redor do location fornecido.
{
  "location": {
    "lat": 37.421875199999995,
    "lng": -122.0851173
  },
  "accuracy": 120
}

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

  • Pontos de acesso Wi-Fi: se a solicitação incluir dois ou mais wifiAccessPoints, o raio de precisão retornado geralmente será 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 normalmente 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 vai usar cellTowers para a localização. A precisão varia significativamente de acordo com o tipo de torre de celular, a intensidade do sinal e a densidade da rede:
    • As células macro (o tipo mais comum, usado para cobertura de área ampla) oferecem menor precisão. O raio geralmente é de centenas de metros, mas pode chegar a 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 precisão geralmente é maior para torres de celular com sinais fortes. Sinais fortes são normalmente > -110 dBm para LTE (intervalo de sinal de -140 a -55 dBm), > -100 dBm para WCDMA (intervalo de sinal de -111 a -53 dBm), > -100 dBm para CDMA (intervalo de sinal de -120 a -40 dBm) e > -80 dBm para GSM (intervalo de sinal de -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 vai estimar o local 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.