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:

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

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

Calculando cellId

Os tipos de rádio anteriores à NR (5G) usam o campo cellId de 32 bits para transmitir a rede e o ID de celular para a API de geolocalização.

• 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 da estação base (BID) de 16 bits no estado em que se encontram. Intervalo válido: 0–65535.
• 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.

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
}

Descartando pontos de acesso Wi-Fi não utilizados

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 das entradas, mas não mostre as mitigações que você pode, já que o aplicativo engenheiro de nuvem, opte por se candidatar.

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:

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")));
    

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')]
    

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 estimada, em metros. Representa o raio de um círculo ao redor de um location:

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