Introdução
A API Geolocation retorna um local e um raio de precisão com base nas informações sobre torres de celular e nós de rede Wi-Fi que o cliente de dispositivos móveis pode detectar. Neste documento, descrevemos o protocolo usado para enviar esses dados ao servidor e retornar uma resposta ao cliente.
A comunicação é realizada por HTTPS usando POST. Tanto a solicitação quanto a resposta são
formatadas como JSON, e o tipo de conteúdo de ambas é
application/json
.
Antes de começar
Antes de começar a desenvolver com a API Geolocation, leia os requisitos de autenticação (uma chave de API) e as informações de Uso e faturamento da API (ative o faturamento no seu projeto).
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
Especifique uma chave na solicitação, incluída como o valor de um parâmetro key
. Uma key
é a chave de API do seu aplicativo. Essa chave identifica seu aplicativo para fins de gerenciamento de cotas. Saiba como criar 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 compatíveis e todos os campos são opcionais, a menos que especificado de outra forma:
Campo | Tipo de JSON | Descrição | Observações |
---|---|---|---|
homeMobileCountryCode |
number (uint32 ) |
O código de país móvel (MCC) da rede home 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 home do dispositivo.
Este é o MNC para GSM, WCDMA, LTE e NR. CDMA usa o ID do sistema (SID) |
Intervalo válido para MNC: 0 a 999. Intervalo válido para SID: 0 a 32.767. |
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 sempre precisará ser incluído se o tipo de rádio for
conhecido pelo cliente. Se o campo for omitido, a API Geolocation usará como padrão gsm , o que resultará em resultados inválidos ou zero se o tipo de rádio incorreto estiver incorreto. |
carrier |
string |
o nome da operadora. | |
considerIp |
boolean |
Especifica se a geolocalização de IP será usada se os sinais da torre de celular e do Wi-Fi 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 desativar
o substituto. |
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. |
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 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 Calcular célula de ID 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 de área local (LAC, na sigla em inglês) para redes GSM e WCDMA. O ID de 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 a 65.535.Intervalo válido com nr : 0 a 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: 0 a 999. |
mobileNetworkCode |
number (uint32 ) |
Código de rede móvel da torre de celular.
Este é o MNC para GSM, WCDMA, LTE e NR. CDMA usa o ID do sistema (SID). |
Obrigatório. Intervalo válido para MNC: 0 a 999. Intervalo válido para SID: 0 a 32.767. |
Os campos opcionais a seguir não são usados no momento, mas podem ser incluídos se houver valores 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 é 0, o cellId ou newRadioCellId representa uma medição atual. |
signalStrength |
number (double ) |
a força do sinal de rádio medida em dBm. | |
timingAdvance |
number (double ) |
O valor de antecipação do tempo. |
Calculando cellId
Os tipos de rádio anteriores à NR (5G) usam o campo cellId
de 32 bits para transmitir o ID da célula de rede para a API Geolocation.
- As redes GSM (2G) usam o ID de célula (CID) de 16 bits como está. Intervalo válido: 0 a 65.535.
- As redes CDMA (2G) usam o ID da estação de base (BID) de 16 bits como está. Intervalo válido: 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 que concatena o identificador de controlador de rede de rádio (RNC-ID) de 12 bits e o ID de 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 de célula de 16 bits em redes WCDMA resultará em resultados incorretos ou zero. - As redes LTE (4G) usam a identidade de célula E-UTRAN (ECI, na sigla em inglês), que é um valor inteiro de 28 bits que concatena o identificador de nó B de 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 da célula de 8 bits em redes LTE resultará em resultados incorretos ou zero.
Colocar valores fora desses intervalos na solicitação da API pode resultar em um comportamento indefinido. A critério do Google, o critério pode truncar o número para que se encaixe no intervalo documentado, inferir uma correção do radioType
ou retornar um resultado NOT_FOUND
sem qualquer indicador na resposta.
Veja 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élula maiores que 32 bits usam o campo newRadioCellId
de 64 bits para transmitir o ID da célula de rede para a API Geolocation.
- As redes NR (5G) usam a nova Radio Cell Identity (NCI) de 36 bits.
Intervalo válido: 0 a 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
os outros campos são opcionais.
Campo | Tipo de JSON | Descrição | Observações |
---|---|---|---|
macAddress |
string |
É o endereço MAC do nó de Wi-Fi. Normalmente, é chamado de BSS, BSSID ou endereço MAC. | Obrigatório. String hexadecimal separada por : (dois-pontos). |
signalStrength |
number (double ) |
a intensidade atual do sinal medida em dBm. | Para pontos de acesso Wi-Fi, os valores de dBm costumam ser -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 medida em dB. |
Veja abaixo um exemplo de objeto de ponto de acesso Wi-Fi.
{ "macAddress": "9c:1c:12:b0:45:f1", "signalStrength": -43, "signalToNoiseRatio": 0, "channel": 11, "age": 0 }
Respostas de geolocalização
Uma solicitação de geolocalização bem-sucedida retornará uma resposta formatada em JSON que define um local e um raio.
location
: a latitude e longitude estimadas do usuário em graus. Contém um subcampolat
elng
.accuracy
: a precisão da localização estimada, em metros. Isso representa o raio de um círculo ao redor dolocation
especificado.
{ "location": { "lat": 37.421875199999995, "lng": -122.0851173 }, "accuracy": 120 }
Erros
No caso de um erro, um corpo de resposta de erro com formato padrão será retornado e o código de status HTTP será definido como um status de erro.
A resposta contém um objeto com um único objeto error
que inclui as seguintes chaves:
code
: este é o mesmo status HTTP da resposta.message
: é uma breve descrição do erro.errors
: uma lista de erros que ocorreram. Cada erro contém um identificador para o tipo de erro (reason
) e uma breve descrição (omessage
).
Por exemplo, o envio de um JSON inválido retorna o seguinte erro:
{ "error": { "errors": [ { "domain": "global", "reason": "parseError", "message": "Parse Error", } ], "code": 400, "message": "Parse Error" } }
Possíveis erros incluem:
Motivo | Domínio | Código de status HTTP | Descrição |
---|---|---|---|
dailyLimitExceeded |
usageLimits |
403 | Você excedeu seu limite diário. |
keyInvalid |
usageLimits |
400 | Sua chave de API não é válida para a API Geolocation. Verifique se você incluiu a chave inteira e se comprou a API ou ativou o faturamento e a API para receber a cota sem custos financeiros. |
userRateLimitExceeded |
usageLimits |
403 | Você excedeu o limite de solicitações configurado no Console do Google Cloud. Esse limite normalmente é definido como solicitações por dia, por 100 segundos e por 100 segundos por usuário. Esse limite precisa ser configurado para evitar que um único ou pequeno grupo de usuários consuma sua cota diária, enquanto mantém um acesso razoável a todos os usuários. Consulte Como limitar o uso da API para configurar esses limites. |
notFound |
geolocation |
404 | A solicitação era válida, mas não retornou resultados. |
parseError |
global |
400 | O corpo da solicitação não é um JSON válido. Consulte a seção Corpo da solicitação para ver detalhes sobre cada campo. |
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": "94:b4:0f:fd:c1:40", "signalStrength": -35, "signalToNoiseRatio": 0 } ] }
Você pode usar 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 dos endereços Mac acima aparece desta forma:
{ "location": { "lat": 37.4241876, "lng": -122.0917381 }, "accuracy": 32.839 }
Consulte Acessar uma chave de API se você não tiver uma.
Para fazer outros testes, você pode coletar informações do seu dispositivo Android usando o SDK do Places para Android e as APIs Android Location e, no dispositivo iOS, usando o SDK do Places para iOS.
Perguntas frequentes
Por que estou recebendo um raio accuracy
muito grande na minha resposta de geolocalização?
Se a resposta de geolocalização mostrar um valor muito alto no campo accuracy
, o serviço pode ser geolocalizado com base no IP de solicitação, em vez de pontos de Wi-Fi ou torres de celular. Isso pode acontecer se nenhuma
torre de celular ou ponto de acesso for válido ou reconhecido.
Para confirmar que esse é o problema, defina considerIp
como false
na solicitação. Se a resposta é um 404
, você confirmou que seus objetos wifiAccessPoints
e cellTowers
não puderam ser geolocalizados.