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 em sua solicitação, incluída como o valor de um parâmetro key. Um key é o arquivo Chave de API. Esta chave identifica seu aplicativo para fins de cota de projetos. 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 são retornados com base no endereço IP do local da solicitação. Os campos a seguir são têm suporte e todos os campos são opcionais, salvo indicação em contrário:

Campo	Tipo de JSON	Descrição	Observações
`homeMobileCountryCode`	`number` (`uint32`)	O código do país para dispositivos móveis (MCC) da rede inicial 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 residencial do dispositivo. Esse é o MNC para GSM, WCDMA, LTE e NR. CDMA usa o ID de sistema (SID)	Intervalo válido para MNC: de 0 a 999. Intervalo válido para SID: 0–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`. Definir `considerIp` como `false` para evitar 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 a seguir.

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 torres 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 opção.
`newRadioCellId`	`number` (`uint64`)	Identificador exclusivo da célula NR (5G).	Obrigatório para `radioType` `nr`. rejected para outros tipos Consulte a seção Calcular 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, na sigla em inglês) 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. Intervalo válido com `gsm`, `cdma`, `wcdma` e `lte`: 0–65.535 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 para GSM, WCDMA, LTE e NR. O CDMA usa o ID de sistema (SID).	Obrigatório. Intervalo válido para MNC: de 0 a 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 forem 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, o `cellId` ou `newRadioCellId` representa uma de medida.
`signalStrength`	`number` (`double`)	a força do sinal de rádio medida em dBm.
`timingAdvance`	`number` (`double`)	O 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 no estado em que se encontram. Intervalo válido: 0–65535.
As redes CDMA (2G) usam o ID de estação base (BID) de 16 bits como está. Faixa válida: 0 a 65.535.
As redes WCDMA (3G) usam a identidade de celular UTRAN/GERAN (UC-ID), que é um número inteiro de 28 bits concatenando o identificador do controlador de rede de rádio de 12 bits (RNC-ID) e o de 16 bits ID da célula (CID).
Fórmula: rnc_id << 16 | cid.
Intervalo válido: 0 a 268435455.
Observação: especificar apenas o valor de ID de celular de 16 bits em redes WCDMA resulta em resultados incorretos ou sem nenhum.
As redes LTE (4G) usam a identidade de celular E-UTRAN, que é um valor inteiro de 28 bits concatenando o identificador do 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 a 268435455.
Observação: especificar apenas o valor de ID de celular de 8 bits em redes LTE resulta em resultados incorretos ou sem nenhum.

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 se encaixe no intervalo documentado, inferir um a correção de radioType, ou retornar um resultado NOT_FOUND sem nenhuma 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 a rede de 64 bits Campo newRadioCellId para transmitir o ID de célula de rede para API de geolocalização.

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–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 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 endereço BSS, BSSID ou MAC.	Obrigatório.String hexadecimal separada por dois pontos (`:`). Somente administrado universalmente Os endereços MAC podem ser localizados pela API. Outros endereços MAC são ser descartado silenciosamente e pode fazer com que uma solicitação de API se torne eficaz vazio. Para mais detalhes, consulte Como descartar o acesso Wi-Fi inútil pontos.
`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 menores e variam de -128 a -10 dBm. Inclua 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 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 um exemplo dados, 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 faça 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
}

Excluir pontos de acesso Wi-Fi não usados

Remover objetos de ponto de acesso Wi-Fi com macAddresss que estão administrado 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 de geolocalização não tenham êxito, mitigações como o uso de sinais de localização mais antigos ou APs Wi-Fi com sinais mais fracos podem ser usados. Essa abordagem é uma troca entre suas a necessidade do aplicativo de uma estimativa de localização e a precisão e o recall e cumprimento de requisitos regulatórios. 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 sinais úteis de localização para o API e são silenciosamente descartadas das solicitações. É possível remover esses endereços MAC garantindo que o segundo bit menos significativo O byte mais significativo de macAddress é 0. Por exemplo: as 1 bit representado pelo 2 em 02:00:00:00:00:00. O endereço MAC da transmissão (FF:FF:FF:FF:FF:FF) é um exemplo de endereço MAC que seria excluídos por esse filtro.

O intervalo de endereços MAC entre 00:00:5E:00:00:00 e 00:00:5E:FF:FF:FF são reservado para IANA e muitas vezes usada para gerenciamento de rede e funções multicast o que impede o uso deles como sinal de localização. Você também deve remover endereços MAC das entradas para a API.

Por exemplo, endereços MAC utilizáveis para geolocalização podem ser coletados de um 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 este filtro resulta em apenas 1c:34:56:78:9a:bc restantes na lista. Como essa lista tem menos de dois endereços MAC de Wi-Fi, o solicitação não teria êxito, e um erro HTTP 404 (notFound) response será retornada.

Respostas de geolocalização

Uma solicitação de geolocalização bem-sucedida retorna uma resposta em formato JSON definindo um local e um raio.

location: a latitude e a longitude estimadas do usuário coordenadas, em graus. Contém um lat e um lng .
accuracy: a precisão da localização aproximada, 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
}