Pronto!

Para começar a desenvolver, acesse nossa documentação do desenvolvedor.

Ativar a Google Maps Geolocation API

Para começar, orientaremos você pelo Google Developers Console para realizar algumas atividades:

  1. Criar ou selecionar um projeto
  2. Ativar a Google Maps Geolocation API
  3. Criar chaves apropriadas
Continuar

A Google Maps Geolocation API

Visão geral

A Google Maps Geolocation API retorna uma localização e um raio de precisão com base em informações de torres de celular e nós Wi-Fi que o cliente móvel pode detectar. Este documento descreve 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 têm formatação JSON e o tipo de conteúdo de ambas é application/json.

Antes de começar a desenvolver com a Geolocation API, consulte os requisitos de autenticação (chave de API necessária) e os limites de uso de API.

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. O parâmetro key é a chave de API do seu aplicativo. Essa chave identifica o aplicativo para fins de gerenciamento de cotas. Saiba como obter uma chave.

Corpo da solicitação

O corpo da solicitação deve ter formatação JSON. Os campos a seguir são permitidos e todos os campos são opcionais:

  • homeMobileCountryCode: o código de país móvel (MCC) da rede inicial do dispositivo.
  • homeMobileNetworkCode: o código de rede móvel (MNC) da rede inicial do dispositivo.
  • radioType: o tipo de rádio móvel. Os valores permitidos são lte, gsm, cdma e wcdma. Embora esse campo seja opcional, ele deve ser incluído como valor, se estiver disponível, para proporcionar resultados mais precisos.
  • carrier: o nome da operadora.
  • considerIp: especifica se a geolocalização por IP deverá ser usada se sinais de Wi-Fi e torres de celular não estiverem disponíveis. Observe que o endereço IP no cabeçalho da solicitação pode não ser o IP do dispositivo. O valor padrão é true. Defina considerIp como false para desativar essa opção.
  • cellTowers: uma matriz de objetos de torre de celular. Consulte a seção Objetos de torre de celular abaixo.
  • wifiAccessPoints: uma matriz de objetos de ponto de acesso Wi-Fi. Consulte a seção Objetos de ponto de acesso Wi-Fi abaixo.
{
  "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.

  • cellId (obrigatório): identificador exclusivo do celular. Em redes GSM, esse valor é o ID de celular (CID). Redes CDMA usam o ID de estação base (BID). Redes WCDMA usam a identidade de celular UTRAN/GERAN (UC-Id), que é um valor de 32 bits que concatena o controlador da rede de rádio (RNC) e o ID de celular. Especificar somente o valor de ID de celular de 16 bits em redes WCDMA pode retornar resultados imprecisos.
  • locationAreaCode (obrigatório): O código de área de localização (LAC) para redes GSM e WCDMA. O ID de rede (NID) para redes CDMA.
  • mobileCountryCode (obrigatório): o código de país móvel (MCC) da torre de celular.
  • mobileNetworkCode (obrigatório): o código de rede móvel da torre de celular. Esse parâmetro é o MNC de redes GSM e WCDMA. Redes CDMA usam o ID de sistema (SID).

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

  • age: o número de milissegundos desde que o celular era primário. Se o valor é 0, o cellId representa uma medida atual.
  • signalStrength: a força do sinal de rádio medida em dBm.
  • timingAdvance: o valor de avanço de tempo.

Veja abaixo um exemplo de objeto de torre de celular GSM.

{
  "cellTowers": [
    {
      "cellId": 42,
      "locationAreaCode": 415,
      "mobileCountryCode": 310,
      "mobileNetworkCode": 410,
      "age": 0,
      "signalStrength": -60,
      "timingAdvance": 15
    }
  ]
}

Veja abaixo um exemplo de objeto de torre de celular WCDMA.

{
  "cellTowers": [
    {
      "cellId": 21532831,
      "locationAreaCode": 2862,
      "mobileCountryCode": 214,
      "mobileNetworkCode": 7
    }
  ]
}

Objetos de ponto de acesso Wi-Fi

A matriz wifiAccessPoints do corpo da solicitação deve conter dois ou mais objetos de ponto de acesso Wi-FI. O macAddress é obrigatório, mas os demais campos são opcionais.

  • macAddress: (obrigatório) o endereço MAC do nó Wi-Fi. Os separadores devem ser : (dois pontos).
  • signalStrength: a intensidade atual do sinal medida em dBm.
  • age: o número de milissegundos desde que o ponto de acesso foi detectado.
  • channel: o canal pelo qual o cliente se comunica com o ponto de acesso.
  • signalToNoiseRatio: 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": "00:25:9c:cf:1c:ac",
  "signalStrength": -43,
  "age": 0,
  "channel": 11,
  "signalToNoiseRatio": 0
}

Respostas de geolocalização

Uma solicitação de geolocalização bem-sucedida retorna uma resposta com formatação JSON que define uma localização e um raio.

  • location: a estimativa de latitude e longitude do usuário, em graus. Contém um subcampo lat e um lng.
  • accuracy: a precisão da localização estimada, em metros. Isso representa o raio de um círculo em torno do location em questão.
{
  "location": {
    "lat": 51.0,
    "lng": -0.1
  },
  "accuracy": 1200.4
}

Erros

Em caso de erros, 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 só objeto error, que inclui as chaves a seguir:

  • code: esse valor é o mesmo que o status HTTP da resposta.
  • message: uma breve descrição do erro.
  • errors: uma lista dos erros que ocorreram. Cada erro contém um identificador para o tipo de erro (reason) e uma breve descriçã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 o limite diário.
keyInvalid usageLimits 400 Sua chave de API não é válida para a Google Maps Geolocation API. Certifique-se de usar a chave inteira, além de comprar a API ou ativar a cobrança e a API para obter a cota gratuita.
userRateLimitExceeded usageLimits 403 Você excedeu o limite de solicitações por segundo por usuário configurado no Google API Console. Esse limite deve ser configurado para evitar que um usuário ou grupo de usuários esgote sua cota diária, mas ainda assim permitir um acesso razoável para todos os usuários.
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 saber mais sobre cada campo.

Exemplos de solicitação

Se quiser experimentar a Google Maps Geolocation API com exemplos de dados, salve o seguinte JSON em um arquivo:

{
  "considerIp": "false",
  "wifiAccessPoints": [
    {
        "macAddress": "00:25:9c:cf:1c:ac",
        "signalStrength": -43,
        "signalToNoiseRatio": 0
    },
    {
        "macAddress": "00:25:9c:cf:1c:ad",
        "signalStrength": -55,
        "signalToNoiseRatio": 0
    }
  ]
}

Você pode usar cURL para fazer a 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 acima aparece desta forma:

{
  "location": {
    "lat": 33.3632256,
    "lng": -117.0874871
  },
  "accuracy": 20
}

Consulte Obter uma chave se não tiver uma chave de API.

Para testes adicionais, é possível coletar informações do seu dispositivo Android usando o Google Places API for Android e as Android Location APIs, e do seu dispositivo iOS usando o Google Places API for iOS.

Perguntas frequentes

Por que estou recebendo um raio de accuracy tão grande na minha resposta de geolocalização?

Se sua resposta de geolocalização apresenta um valor muito alto no campo accuracy, o serviço pode estar executando a geolocalização com base no IP da solicitação, não nos pontos de Wi-FI ou nas torres de celular. Isso poderá acontecer se nenhuma torre de celular nem ponto de acesso for válido ou reconhecido.

Para confirmar o ocorrido, defina considerIp como false na solicitação. Se a resposta for 404, você confirmou que não foi possível geolocalizar seus objetos wifiAccessPoints e cellTowers.

Enviar comentários sobre…

Google Maps Geolocation API
Google Maps Geolocation API
Precisa de ajuda? Acesse nossa página de suporte.