Eso es todo.

Para comenzar a desarrollar, consulta nuestra documentación para desarrolladores.

Activar la Google Maps Geolocation API

Para que puedas comenzar, te proporcionaremos orientación en la Google Developers Console a fin de que hagas primero algunas acciones:

  1. Crear o seleccionar un proyecto
  2. Activar la Google Maps Geolocation API
  3. Crear claves correspondientes
Continuar

Google Maps Geolocation API

Información general

Google Maps Geolocation API devuelve una ubicación y radios de precisión en función de información acerca de torres celulares y nodos de WiFi que el cliente móvil pueda detectar. Este documento describe el protocolo utilizado para enviar estos datos al servidor y devolver una respuesta al cliente.

La comunicación se realiza a través de HTTPS usando POST. Tanto la solicitud como la respuesta poseen formato JSON, y el tipo de contenido de ambas es application/json.

Antes de comenzar a realizar desarrollos con la Geolocation API, revisa los requisitos de autenticación (necesitas una clave de API) y los límites de uso de la API.

Solicitudes de geolocalización

Las solicitudes de geolocalización se envían usando POST a la siguiente dirección URL:

https://www.googleapis.com/geolocation/v1/geolocate?key=YOUR_API_KEY

Debes especificar una clave en tu solicitud e incluirla como el valor de un parámetro key. Una key es la clave de API de tu aplicación. Esta clave identifica tu aplicación a los fines de la administración de la cuota. Infórmate acerca de cómo obtener una clave.

Cuerpo de la solicitud

El cuerpo de la solicitud debe tener formato JSON. Se admiten los siguientes campos, y todos son opcionales:

  • homeMobileCountryCode: El código de país móvil (MCC) para la red local del dispositivo.
  • homeMobileNetworkCode: El código de red móvil (MNC) para la red local del dispositivo.
  • radioType: El tipo de radio móvil. Los valores admitidos son lte, gsm, cdma y wcdma. Si bien este campo es opcional, se lo debe incluir si hay un valor disponible para obtener resultados más exactos.
  • carrier: Nombre del proveedor.
  • considerIp: Especifica si se debe volver a la geolocalización de IP en caso de que no haya señales de wifi y torres celulares disponibles. Ten en cuenta que la dirección IP que se indica en el encabezado de la solicitud puede no ser la IP del dispositivo. El valor predeterminado es true. Configura considerIp en false para deshabilitar el regreso a la IP.
  • cellTowers: Una matriz de objetos de torres celulares. Consulta la sección Objetos de torres celulares a continuación.
  • wifiAccessPoints: Una matriz de objetos de punto de acceso WiFi. Consulta la sección Objetos de punto de acceso WiFi a continuación.
{
  "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 torres celulares

La matriz cellTowers del cuerpo de la solicitud contiene cero o más objetos de torres celulares.

  • cellId (obligatorio): Identificador único del celular. En GSM, es el id. del celular (CID); las redes CDMA usan el id. de la estación base (BID). Las redes WCDMA usan identificación celular UTRAN/GERAN (UC-Id), un valor de 32 bits que concatena el ID del Controlador de la red de radio (RNC) y del celular. Si solo se especifica el valor de ID de celular de 16 bits en las redes WCDMA, podrían mostrarse resultados imprecisos.
  • locationAreaCode (obligatorio): El Código de área del sitio (LAC) para redes GSM y WCDMA. El id. de red (NID) para redes CDMA.
  • mobileCountryCode (obligatorio): El código de país móvil (MCC) de la torre celular.
  • mobileNetworkCode (obligatorio): El código de red móvil de la torre celular. Es decir, el MNC para GCM y WCDMA; CDMA usa el id. del sistema (SID).

Los siguientes campos opcionales no se utilizan actualmente, pero se pueden incluir si hay valores disponibles.

  • age: La cantidad de milisegundos desde que el celular era primario. Si la edad es 0, el cellId representa una medición actual.
  • signalStrength: Potencia de la señal de radio medida en dBm.
  • timingAdvance: El valor de avance de tiempo.

A continuación, se muestra un ejemplo de objeto de torre celular GSM.

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

A continuación, se muestra un ejemplo de objeto de torre celular WCDMA.

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

Objetos de punto de acceso WiFi

La matriz wifiAccessPoints del cuerpo de la solicitud debe contener dos o más objetos de punto de acceso WiFi. macAddress es obligatorio; todos los demás campos son opcionales.

  • macAddress: (obligatorio) La dirección MAC del nodo WiFi. Los separadores deben ser : (dos puntos).
  • signalStrength: La potencia actual de la señal medida en dBm.
  • age: La cantidad de milisegundos transcurridos desde que se detectó este punto de acceso.
  • channel: El canal por el que el cliente se comunica con el punto de acceso.
  • signalToNoiseRatio: La relación señal-ruido actual medida en dBm.

A continuación, se muestra un ejemplo de objeto de punto de acceso WiFi.

{
  "macAddress": "00:25:9c:cf:1c:ac",
  "signalStrength": -43,
  "age": 0,
  "channel": 11,
  "signalToNoiseRatio": 0
}

Respuestas a solicitudes de geolocalización

Una solicitud de geolocalización exitosa devolverá una respuesta en formato JSON que definirá una ubicación y un radio.

  • location: La latitud y longitud calculadas del usuario, en grados. Contiene un subcampo lat y uno lng.
  • accuracy: La precisión de la ubicación calculada, en metros. Esto representa el radio de un círculo alrededor de la location especificada.
{
  "location": {
    "lat": 51.0,
    "lng": -0.1
  },
  "accuracy": 1200.4
}

Errores

Si ocurre un error, se devolverá una respuesta al error en formato estándar y se establecerá el código de estado HTTP en un estado de error.

La respuesta contiene un objeto con un solo objeto error y las siguientes claves:

  • code: la misma que el estado HTTP de la respuesta.
  • message: una descripción breve del error.
  • errors: una lista de los errores que ocurrieron. Cada error contiene un identificador para el tipo de error (reason) y una descripción breve (message).

Por ejemplo, si envías una solicitud en formato JSON, se devolverá el siguiente error:

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "parseError",
    "message": "Parse Error",
   }
  ],
  "code": 400,
  "message": "Parse Error"
 }
}

Los errores posibles incluyen los siguientes:

Motivo Dominio Código de estado HTTP Descripción
dailyLimitExceeded usageLimits 403 Excediste tu límite diario.
keyInvalid usageLimits 400 Tu clave de API no es válida para Google Maps Geolocation API. Asegúrate de haber incluido la clave completa y de haber comprado la API o habilitado la facturación y activado la API para obtener la cuota gratuita.
userRateLimitExceeded usageLimits 403 Superaste el límite de solicitudes por segundo por usuario que configuraste en la Google API Console. Se debe configurar este límite para evitar que un usuario o un grupo de usuarios agoten tu cuota diaria, y para poder continuar ofreciendo acceso razonable a todos los usuarios.
notFound geolocation 404 La solicitud fue válida, pero no se devolvieron resultados.
parseError global 400 El cuerpo de la solicitud no posee formato JSON válido. Consulta la sección Cuerpo de la solicitud para obtener información detallada acerca de cada campo.

Ejemplos de solicitudes

Si quieres probar la Google Maps Geolocation API con datos de ejemplo, guarda el siguiente JSON en un archivo:

{
  "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
    }
  ]
}

Luego, podrás usar cURL para realizar tu solicitud desde la línea de comandos:

$ curl -d @your_filename.json -H "Content-Type: application/json" -i "https://www.googleapis.com/geolocation/v1/geolocate?key=YOUR_API_KEY"

La respuesta para las direcciones Mac antes mencionadas tiene el siguiente aspecto:

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

(Si no tienes una clave de API, consulta Obtener una clave).

Para realizar más pruebas, puedes reunir información de tu dispositivo Android usando la Google Places API for Android y las Android Location API, y también de tu dispositivo iOS, con la Google Places API for iOS.

Preguntas frecuentes

¿Por qué obtengo un radio de accuracy muy amplio en la respuesta a mi solicitud de geolocalización?

Si la respuesta a tu solicitud de geolocalización muestra un valor muy alto en el campo accuracy, es posible que el servicio esté geolocalizando en función de la IP desde donde se envió la solicitud, en lugar de hacerlo a partir de los puntos WiFi o las torres celulares. Esto puede ocurrir si no se reconocen torres celulares o puntos de acceso, o sin no son válidos.

Para confirmar si este es el problema, configura considerIp en false en tu solicitud. Si la respuesta es 404, haz confirmado que tus objetos wifiAccessPoints y cellTowers no pudieron geolocalizarse.

Enviar comentarios sobre...

Google Maps Geolocation API
Google Maps Geolocation API
Si necesitas ayuda, visita nuestra página de asistencia.