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

É necessário especificar uma chave na solicitação, incluída como o valor de um parâmetro key. Um 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 seguintes campos são compatíveis e todos são opcionais, a menos que seja indicado o 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 doméstica do dispositivo.	Aceito para `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 deve sempre ser incluído se 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 zero 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 os sinais de Wi-Fi e da 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 o retorno.
`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 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 newRadioCellId abaixo, que também lista o intervalo de valores válidos para o campo.
`locationAreaCode`	`number` (`uint32`)	O código da área de localização (LAC) para redes GSM e WCDMA. O ID da 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 a 999.
`mobileNetworkCode`	`number` (`uint32`)	O código de rede móvel da torre de celular. É o MNC para GSM, WCDMA, LTE e NR. O CDMA usa o ID do sistema (SID).	Obrigatório. Intervalo válido para MNC: 0 a 999. Intervalo válido para SID: 0 a 32767.

Os seguintes campos opcionais 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 medição atual.
`signalStrength`	`number` (`double`)	a força do sinal de rádio medida em dBm.
`timingAdvance`	`number` (`double`)	O valor do antecipação de tempo.

Calculando `cellId`

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

As redes GSM (2G) usam o ID da célula (CID) 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), 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 da célula (CID) de 16 bits.
Fórmula: rnc_id << 16 | cid.
Intervalo válido: 0 a 268435455.
Observação:especificar apenas o valor de ID da célula de 16 bits em redes WCDMA resulta em resultados incorretos ou zero.
As redes LTE (4G) usam a identidade de célula E-UTRAN (ECI), que é um valor inteiro de 28 bits que concatena o identificador de nó B E-UTRAN de 20 bits (eNBId) e o ID da célula de 8 bits (CID).
Fórmula: enb_id << 8 | cid.
Intervalo válido: 0 a 268435455.
Observação:especificar apenas o valor de ID da célula de 8 bits em redes LTE resulta em resultados incorretos ou zero.

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.

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 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 nova rádio (NCI, na sigla em inglês) de 36 bits como está.
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. 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 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 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 relação sinal-ruído atual 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 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 para os endereços MAC anteriores é assim:

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

Descartar pontos de acesso Wi-Fi não utilizados

Remover objetos de ponto de acesso Wi-Fi com macAddresses administradas localmente pode melhorar a taxa de sucesso das chamadas da API Geolocation que usam Wi-Fi como entrada. Se, após a filtragem, for possível determinar que uma chamada da API Geolocation não será bem-sucedida, poderão ser usadas mitigações, como o uso de indicadores de localização mais antigos ou pontos de acesso Wi-Fi com sinais mais fracos. Essa abordagem é uma compensação entre a necessidade de uma estimativa de local e os requisitos de precisão e recall do aplicativo. 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.

Endereços MAC administrados localmente não são indicadores de localização úteis para a API e são descartados silenciosamente das solicitações. Para remover esses endereços MAC, verifique se o segundo bit menos significativo do byte mais significativo de macAddress é 0. Por exemplo, o 1 bit representado por 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 forma ú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 usado com frequência para funções de gerenciamento de rede e multicast, o que impede o uso deles como um indicador de local. Também é necessário remover esses endereços MAC das entradas da 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');

Usar esse filtro resulta em apenas 1c:34:56:78:9a:bc restantes 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 estimadas de latitude e longitude do usuário, em graus. Contém um subcampo lat e um lng.
accuracy: a precisão do local estimado, em metros. Isso representa o raio de um círculo ao redor do location especificado.

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