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 deverá sempre ser incluído se o tipo de opção for
conhecidas pelo cliente. Se o campo for omitido, o padrão da API Geolocation será gsm .
o que vai resultar em resultados inválidos ou zero se o tipo de opção presumido for
incorreto. |
carrier |
string |
o nome da operadora. | |
considerIp |
boolean |
Especifica se a geolocalização por IP deverá ser usada se os sinais de Wi-Fi e de torres de celular estiverem ausentes vazio ou não suficiente 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. |
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.
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
tiposConsulte 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.535Intervalo 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 à 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.
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 em dBm normalmente são -35 ou menos 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 }
Descartando pontos de acesso Wi-Fi não utilizados
Remover objetos de ponto de acesso Wi-Fi com macAddress
s 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
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 umlat
e umlng
.accuracy
: a precisão da localização aproximada, em metros. Representa o raio de um círculo ao redor de umlocation
:
{ "location": { "lat": 37.421875199999995, "lng": -122.0851173 }, "accuracy": 120 }