Visão geral

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

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 subcampo lat e lng.
  • accuracy: a precisão da localização estimada, em metros. Isso representa o raio de um círculo ao redor do location 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 (o message).

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.