Esta página foi traduzida pela API Cloud Translation.

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

Você deve especificar uma chave na solicitação, incluída como o valor de um parâmetro key. Um 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 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 permitidos, e todos os campos são opcionais, a menos que indicado o contrário:

Campo	Tipo de JSON	Descrição	Observações
`homeMobileCountryCode`	`number` (`uint32`)	O código de país móvel (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 a 999.
`homeMobileNetworkCode`	`number` (`uint32`)	O código de rede móvel da rede doméstica do dispositivo. Esse é o MNC para GSM, WCDMA, LTE e NR. O CDMA usa o ID do sistema (SID).	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 incluído sempre que o tipo de rádio for conhecido pelo cliente. Se o campo for omitido, a API Geolocation vai usar `gsm` por padrão, o que vai resultar em resultados inválidos ou nulos se o tipo de rádio presumido estiver incorreto.
`carrier`	`string`	o nome da operadora.
`considerIp`	`boolean`	Especifica se a geolocalização por IP será usada se os 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 a 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 Como calcular o cellId abaixo, que também lista os intervalos de valor 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) 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) para redes LTE e NR.	Obrigatório para `radioType` `gsm` (padrão) e `cdma`, opcional para outros valores. Faixa válida com `gsm`, `cdma`, `wcdma` e `lte`: 0 a 65.535. O intervalo válido com `nr` é 0 a 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 a 999.
`mobileNetworkCode`	`number` (`uint32`)	o código de rede móvel da torre de celular. Esse parâmetro é o MNC de redes GSM, WCDMA, LTE e NR. Redes CDMA usam o ID de sistema (SID).	Obrigatório. O 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 o valor for 0, o `cellId` ou `newRadioCellId` vai 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 ID da célula da rede à API Geolocation.

As redes GSM (2G) usam o ID de celular (CID) de 16 bits como está. Faixa válida: 0 a 65.535.
As redes CDMA (2G) usam o ID da estação base (BID) de 16 bits como está. Faixa válida: 0 a 65.535.
As redes WCDMA (3G) usam a identidade de célula UTRAN/GERAN (UC-ID), que é um valor inteiro de 28 bits concatenando o identificador de controlador de rede de rádio de 12 bits (RNC-ID) e o ID de célula de 16 bits (CID).
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), que é um valor inteiro de 28 bits concatenando o identificador de nó B E-UTRAN (eNBId) de 20 bits e o ID de célula (CID) 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.

Colocar valores fora desses intervalos na solicitação da API pode resultar em comportamento indefinido. A API, a critério do Google, pode truncar o número para que ele se encaixe no 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`

Redes mais recentes, cujos IDs de célula têm mais de 32 bits, usam o campo newRadioCellId de 64 bits para transmitir o ID de célula da rede à API Geolocation.

As redes NR (5G) usam a identidade de célula de 36 bits do New Radio (NCI).
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 que representem dispositivos de ponto de acesso fisicamente distintos. macAddress é obrigatório. 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 geralmente é chamado de BSS, BSSID ou endereço MAC.	Obrigatório: string hexadecimal separada por dois-pontos (`:`). Apenas endereços MAC universalmente administrados podem ser localizados pela 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 Remover 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 são normalmente -35 ou menores 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 de sinal para ruído medida em dB.

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 exemplo, 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 o 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
}

Como remover pontos de acesso Wi-Fi não usados

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 o Wi-Fi como entrada. Se, após a filtragem, for possível determinar que uma chamada da API de geolocalização não teria sucesso, 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 local e os requisitos de precisão e recuperação. As técnicas de filtragem a seguir demonstram como filtrar as entradas, mas não mostram as mitigações que você pode aplicar como engenheiro de aplicativos.

Os endereços MAC administrados localmente não são indicadores de local úteis para a API e são removidos silenciosamente das solicitações. É possível 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 um endereço MAC que seria útilmente excluído 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 de multicast, o que impede 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 = {"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 teria sucesso e uma resposta HTTP 404 (notFound) (link em inglês) 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 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 em questão.

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