Se usó la API de Cloud Translation para traducir esta página.

Solicitud y respuesta de geolocalización

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 la solicitud, incluida como el valor de un parámetro key. Un 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. Descubre cómo obtener una clave.

Cuerpo de la solicitud

El cuerpo de la solicitud debe tener formato JSON. Si no se incluye el cuerpo de la solicitud, los resultados se mostrarán en función de la dirección IP de la ubicación de la solicitud. Se admiten los siguientes campos y todos son opcionales, a menos que se indique lo contrario:

Campo	Tipo JSON	Descripción	Notas
`homeMobileCountryCode`	`number` (`uint32`)	Es el código móvil de país (MCC) de la red particular del dispositivo.	Compatible con `radioType` `gsm` (predeterminado), `wcdma`, `lte` y `nr`; no se usa para `cdma`. Rango válido: 0–999.
`homeMobileNetworkCode`	`number` (`uint32`)	Es el código de red móvil correspondiente a la red particular del dispositivo. Este es el MNC para GSM, WCDMA, LTE y NR. CDMA usa el ID del sistema (SID)	Rango válido para MNC: de 0 a 999. Rango válido para el SID: 0–32767.
`radioType`	`string`	El tipo de radio móvil. Los valores admitidos son `gsm`, `cdma`, `wcdma`, `lte` y `nr`.	Aunque este campo es opcional, siempre se debe incluir si el cliente conoce el tipo de radio. Si se omite el campo, la API de Geolocation se establece de forma predeterminada en `gsm`, lo que da como resultado resultados no válidos o nulos si el tipo de selección supuesto es incorrecto.
`carrier`	`string`	Nombre del proveedor.
`considerIp`	`boolean`	Especifica si se debe volver a la ubicación geográfica de IP en caso de que falten señales de Wi-Fi y de las torres de telefonía celular, estén vacías o no sean suficientes para estimar la ubicación del dispositivo.	La configuración predeterminada es `true`. Establece `considerIp` en `false` para evitar un resguardo.
`cellTowers`	`array`	Una matriz de objetos de torres celulares.	Consulta la sección Objetos de torres celulares a continuación.
`wifiAccessPoints`	`array`	Una matriz de objetos de punto de acceso WiFi.	Consulta la sección Objetos de punto de acceso Wi-Fi a continuación.

A continuación, se muestra un ejemplo de cuerpo de solicitud a la API de 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 torres celulares

El array cellTowers del cuerpo de la solicitud contiene cero o más objetos de torres de telefonía celular.

Campo	Tipo JSON	Descripción	Notas
`cellId`	`number` (`uint32`)	Identificador único del celular.	Obligatorio para `radioType` `gsm` (predeterminado), `cdma`, `wcdma` y `lte`; rechazado para `nr`. Consulta la sección Cómo calcular el ID de la celda a continuación, en la que también se enumeran los rangos de valores válidos para cada tipo de radio.
`newRadioCellId`	`number` (`uint64`)	Identificador único de la celda de NR (5G).	Obligatorio para `radioType` `nr`; rechazado para otros tipos. Consulta la sección Cálculo de newRadioCellId a continuación, que también enumera el rango de valores válido para el campo.
`locationAreaCode`	`number` (`uint32`)	El código de área de la ubicación (LAC) para redes GSM y WCDMA. Es el ID de red (NID) para las redes CDMA. Es el código de área de seguimiento (TAC) para las redes LTE y NR.	Obligatorio para `radioType` `gsm` (predeterminado) y `cdma`, opcional para otros valores. Rango válido con `gsm`, `cdma`, `wcdma` y `lte`: de 0 a 65535. Rango válido con `nr`: 0–16777215.
`mobileCountryCode`	`number` (`uint32`)	El código de país móvil (MCC) de la torre de telefonía celular.	Obligatorio para `radioType` `gsm` (predeterminado), `wcdma`, `lte` y `nr`; no se usa para `cdma`. Rango válido: 0–999.
`mobileNetworkCode`	`number` (`uint32`)	El código de red móvil de la torre celular. Este es el MNC para GSM, WCDMA, LTE y NR. CDMA usa el ID del sistema (SID).	Obligatorio. Rango válido para MNC: de 0 a 999. Rango válido para el SID: 0–32767.

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

Campo	Tipo JSON	Descripción	Notas
`age`	`number` (`uint32`)	La cantidad de milisegundos desde que el celular era primario.	Si la edad es 0, el `cellId` o el `newRadioCellId` representan una medición actual.
`signalStrength`	`number` (`double`)	Potencia de la señal de radio medida en dBm.
`timingAdvance`	`number` (`double`)	El valor del avance del tiempo.

Calculando `cellId`

Los tipos de radio anteriores a NR (5G) usan el campo cellId de 32 bits para pasar el ID de celular de la red a la API de Geolocation.

Las redes GSM (2G) usan el ID de celular (CID) de 16 bits tal como está. Rango válido: de 0 a 65535.
Las redes CDMA (2G) usan el ID de estación base (BID) de 16 bits tal como está. Rango válido: 0–65535.
Las redes WCDMA (3G) usan la identidad celular UTRAN/GERAN (UC-ID), que es un valor entero de 28 bits que concatena el identificador del controlador de red de radio (RNC-ID) de 12 bits y el ID de celular (CID) de 16 bits.
Fórmula: rnc_id << 16 | cid.
Rango válido: 0–268435455.
Nota: Si especificas solo el valor de ID de celular de 16 bits en las redes WCDMA, se generarán resultados incorrectos o no habrá ninguno.
Las redes LTE (4G) usan la identidad móvil E-UTRAN (ECI), que es un valor entero de 28 bits que concatena el identificador del nodo E-UTRAN de 20 bits (eNBId) y el ID de celda (CID) de 8 bits.
Fórmula: enb_id << 8 | cid.
Rango válido: 0–268435455.
Nota: Especificar solo el valor de ID de celular de 8 bits en redes LTE genera resultados incorrectos o nulos.

Colocar valores fuera de estos rangos en la solicitud a la API puede dar como resultado un comportamiento indefinido. La API, a discreción de Google, podría truncar el número para que se ajuste al rango documentado, inferir una corrección en radioType o mostrar un resultado NOT_FOUND sin ningún indicador en la respuesta.

A continuación, se muestra un ejemplo de objeto de torre de telefonía celular LTE.

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

Calculando `newRadioCellId`

Las redes más nuevas, cuyos IDs de celda tienen más de 32 bits usan el campo newRadioCellId de 64 bits para pasar el ID de celda de la red a la API de Geolocation.

Las redes de NR (5G) usan la nueva identidad celular de radio (NCI) de 36 bits sin modificaciones.
Rango válido: 0–68719476735.

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

{
  "cellTowers": [
    {
      "newRadioCellId": 68719476735,
      "mobileCountryCode": 310,
      "mobileNetworkCode": 410,
      "age": 0,
      "signalStrength": -60,
    }
  ]
}

Objetos de punto de acceso WiFi

El array wifiAccessPoints del cuerpo de la solicitud debe contener dos o más objetos de punto de acceso Wi-Fi. macAddress es obligatorio; todos los demás campos son opcionales.

Campo	Tipo JSON	Descripción	Notas
`macAddress`	`string`	Es la dirección MAC del nodo Wi-Fi. Por lo general, se denomina dirección MAC, BSS o BSSID.	Obligatorio: Es una cadena hexadecimal separada por dos puntos (`:`). Solo se pueden ubicar direcciones MAC administradas universalmente a través de la API. Otras direcciones MAC se descartan de forma silenciosa y pueden hacer que una solicitud a la API quede vacía. Para obtener más información, consulta Cómo descartar puntos de acceso Wi-Fi sin uso.
`signalStrength`	`number` (`double`)	La potencia actual de la señal medida en dBm.	Para los puntos de acceso Wi-Fi, los valores de dBm son generalmente de -35 o inferiores y varían de -128 dBm a -10 dBm. Asegúrate de incluir el signo menos.
`age`	`number` (`uint32`)	La cantidad de milisegundos transcurridos desde que se detectó este punto de acceso.
`channel`	`number` (`uint32`)	El canal por el que el cliente se comunica con el punto de acceso.
`signalToNoiseRatio`	`number` (`double`)	La relación señal-ruido actual medida en dB.

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

{
  "macAddress": "9c:1c:12:b0:45:f1",
  "signalStrength": -43,
  "signalToNoiseRatio": 0,
  "channel": 11,
  "age": 0
}

Solicitudes de muestra

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

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

Luego, puedes usar cURL para realizar una 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 anteriores es similar a la siguiente:

{
  "location": {
      "lat": 37.4241876,
      "lng": -122.0917381
  },
  "accuracy": 32.839
}

Descartando puntos de acceso Wi-Fi sin usar

Quitar los objetos de punto de acceso Wi-Fi con macAddress que se administran de forma local puede mejorar la tasa de éxito de las llamadas a la API de Geolocation que usan Wi-Fi como entrada. Si, después del filtrado, se puede determinar que una llamada a la API de Geolocation no tuvo éxito, se pueden usar mitigaciones como el uso de señales de ubicación más antiguas o puntos de acceso de Wi-Fi con señales más débiles. Este enfoque representa una compensación entre la necesidad de tu aplicación de una estimación de la ubicación y sus requisitos de precisión y recuperación. En las siguientes técnicas de filtrado, se muestra cómo filtrar las entradas, pero no se muestran las mitigaciones que puedes aplicar como ingeniero de aplicaciones.

Las direcciones MAC administradas de forma local no son señales de ubicación útiles para la API y se descartan de forma silenciosa de las solicitudes. Para quitar esas direcciones MAC, asegúrate de que el segundo bit menos significativo del byte más significativo de macAddress sea 0, p.ej., el bit de 1 bit que representa 2 en 02:00:00:00:00:00. La dirección MAC de transmisión (FF:FF:FF:FF:FF:FF) es un ejemplo de una dirección MAC que sería útil excluir con este filtro.

El rango de direcciones MAC entre 00:00:5E:00:00:00 y 00:00:5E:FF:FF:FF está reservado para IANA y, a menudo, se usa para funciones de administración de red y multidifusión, lo que excluye su uso como indicador de ubicación. También debes quitar estas direcciones MAC de las entradas de la API.

Por ejemplo, las direcciones MAC que se pueden usar para Geolocation se pueden recopilar de un array de strings macAddress llamado macs:

Java

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")));

Python

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')]

JavaScript

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');

El uso de este filtro hace que solo 1c:34:56:78:9a:bc queden en la lista. Como esta lista tiene menos de 2 direcciones MAC de Wi-Fi, la solicitud no se realizaría correctamente y se mostraría una respuesta (notFound) HTTP 404.

Respuestas a solicitudes de geolocalización

Una solicitud de ubicación geográfica exitosa muestra una respuesta en formato JSON que define una ubicación y un radio.

location: Son las coordenadas de latitud y longitud estimadas del usuario, en grados. Contiene un subcampo lat y un subcampo lng.
accuracy: Es la precisión de la ubicación estimada en metros. Representa el radio de un círculo alrededor de la location especificada.

{
  "location": {
    "lat": 37.421875199999995,
    "lng": -122.0851173
  },
  "accuracy": 120
}