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 tu 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 para la administración de cuotas. Obtén más información para 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 muestran según 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`)	El código móvil de país (MCC) de la red principal del dispositivo	Se admite para `radioType` `gsm` (predeterminado), `wcdma`, `lte` y `nr`; no se usa para `cdma`. Rango válido: 0 a 999.
`homeMobileNetworkCode`	`number` (`uint32`)	El código de red móvil de la red doméstica del dispositivo Esta es la 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: de 0 a 32,767.
`radioType`	`string`	El tipo de radio móvil. Los valores admitidos son `gsm`, `cdma`, `wcdma`, `lte` y `nr`.	Si bien este campo es opcional, debe incluirse siempre si el cliente conoce el tipo de radio. Si se omite el campo, la API de Geolocation usa `gsm` de forma predeterminada, lo que generará resultados no válidos o cero si el tipo de radio asumido es incorrecto.
`carrier`	`string`	Nombre del proveedor.
`considerIp`	`boolean`	Especifica si se debe recurrir a la geolocalización de IP si faltan los indicadores de Wi-Fi y de torres de telefonía celular, están vacíos o no son suficientes para estimar la ubicación del dispositivo.	La configuración predeterminada es `true`. Establece `considerIp` en `false` para evitar el resguardo.
`cellTowers`	`array`	Una matriz de objetos de torres celulares.	Consulta la sección Objetos de torres de telefonía celular a continuación.
`wifiAccessPoints`	`array`	Una matriz de objetos de punto de acceso WiFi.	Consulta la sección Objetos de punto de acceso de Wi-Fi a continuación.

A continuación, se muestra un ejemplo de cuerpo de solicitud de 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 cellId que se encuentra a continuación, en la que también se enumeran los rangos de valores válidos para cada tipo de radio.
`newRadioCellId`	`number` (`uint64`)	Es el identificador único de la celda NR (5G).	Obligatorio para `radioType` `nr`; rechazado para otros tipos. Consulta la sección Cálculo de newRadioCellId que se encuentra a continuación, en la que también se indica el rango de valores válidos para el campo.
`locationAreaCode`	`number` (`uint32`)	Es el código de área de ubicación (LAC) para las 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 65,535. Rango válido con `nr`: De 0 a 16777215.
`mobileCountryCode`	`number` (`uint32`)	El código móvil de país (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 a 999.
`mobileNetworkCode`	`number` (`uint32`)	El código de red móvil de la torre de telefonía celular Esta es la 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: de 0 a 32,767.

Los siguientes campos opcionales no se usan, pero se pueden incluir si los valores están 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, `cellId` o `newRadioCellId` representa una medición actual.
`signalStrength`	`number` (`double`)	Potencia de la señal de radio medida en dBm.
`timingAdvance`	`number` (`double`)	El valor de avance de sincronización

Cálculo de `cellId`

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

Las redes GSM (2G) usan el ID de celda (CID) de 16 bits tal como está. Rango válido: de 0 a 65,535.
Las redes CDMA (2G) usan el ID de estación base (BID) de 16 bits tal como está. Rango válido: de 0 a 65,535.
Las redes WCDMA (3G) usan la identidad de la celda UTRAN/GERAN (UC-ID), que es un valor de número entero de 28 bits que concatena el identificador de controlador de red de radio (RNC-ID) de 12 bits y el ID de celda (CID) de 16 bits.
Fórmula: rnc_id << 16 | cid.
Rango válido: De 0 a 268435455.
Nota: Si especificas solo el valor de ID de celda de 16 bits en redes WCDMA, se generan resultados incorrectos o cero.
Las redes LTE (4G) usan la identidad de la celda E-UTRAN (ECI), que es un valor de número entero de 28 bits que concatena el identificador de nodo B de E-UTRAN (eNBId) de 20 bits y el ID de celda (CID) de 8 bits.
Fórmula: enb_id << 8 | cid.
Rango válido: De 0 a 268435455.
Nota: Si especificas solo el valor de ID de celda de 8 bits en redes LTE, se generan resultados incorrectos o cero.

Si colocas valores fuera de estos rangos en la solicitud a la API, es posible que se genere un comportamiento no definido. La API, a discreción de Google, puede truncar el número para que se ajuste al rango documentado, inferir una corrección en el 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
    }
  ]
}

Cálculo de `newRadioCellId`

Las redes más nuevas, cuyos IDs de celda son más largos que 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 NR (5G) usan la identidad de la nueva celda de radio (NCI) de 36 bits tal como está.
Rango válido: de 0 a 68719476735.

A continuación, se muestra un ejemplo de objeto de torre de telefonía celular 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 de Wi-Fi que representen dispositivos de punto de acceso físicamente distintos. macAddress es obligatorio; todos los demás campos son opcionales.

Campo	Tipo JSON	Descripción	Notas
`macAddress`	`string`	La dirección MAC del nodo Wi-Fi Por lo general, se denomina BSS, BSSID o dirección MAC.	Obligatorio. Es una cadena hexadecimal separada por dos puntos (`:`). Solo se pueden encontrar direcciones MAC administradas de forma universal a través de la API. Otras direcciones MAC se descartan de forma silenciosa y pueden provocar que una solicitud a la API quede efectivamente vacía. Para obtener más información, consulta Cómo quitar puntos de acceso Wi-Fi inútiles.
`signalStrength`	`number` (`double`)	La potencia actual de la señal medida en dBm.	En el caso de los puntos de acceso Wi-Fi, los valores de dBm suelen ser de -35 o menos y van de -128 a -10 dBm. Asegúrate de incluir el signo menos. Para valores superiores a -10 dBm, la API muestra `NOT FOUND`.
`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`)	Es 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": "f0:d5:bf:fd:12:ae",
  "signalStrength": -43,
  "signalToNoiseRatio": 0,
  "channel": 11,
  "age": 0
}

Ejemplos de solicitudes

Si deseas 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": "30:86:2d:c4:29:d0",
      "signalStrength": -35,
      "signalToNoiseRatio": 0
    }
  ]
}

Luego, puedes usar cURL para realizar la 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 de las direcciones MAC anteriores se ve de la siguiente manera:

{
  "location": {
    "lat": 37.4241173,
    "lng": -122.0915717
  },
  "accuracy": 20
}

Cómo quitar puntos de acceso de Wi-Fi que no se usan

Quitar objetos de punto de acceso Wi-Fi con macAddress que se administran de forma local puede mejorar el porcentaje de éxito de las llamadas a la API de Geolocation que usan Wi-Fi como entrada. Si, después de filtrar, se puede determinar que una llamada a la API de Geolocation no se realizaría correctamente, se pueden usar mitigaciones, como usar indicadores de ubicación más antiguos o AP de Wi-Fi con indicadores más débiles. Este enfoque es un compromiso entre la necesidad de tu aplicación de una estimación de 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, como ingeniero de aplicaciones, puedes aplicar.

Las direcciones MAC administradas de forma local no son indicadores de ubicación útiles para la API y se quitan de las solicitudes de forma silenciosa. Para quitar esas direcciones MAC, debes asegurarte de que el segundo bit menos significativo del byte más significativo de macAddress sea 0, p.ej., el bit 1 representado por 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 este filtro excluiría de forma útil.

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

Por ejemplo, las direcciones MAC utilizables para la geolocalización se pueden recopilar de un array de cadenas macAddress llamadas 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');

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

Respuestas a solicitudes de geolocalización

Una solicitud de geolocalización correcta muestra una respuesta en formato JSON que define una ubicación y un radio.

location: Las coordenadas de latitud y longitud estimadas del usuario, en grados Contiene un subcampo lat y uno lng.
accuracy: Es la precisión de la ubicación estimada, en metros. Esto representa el radio de un círculo alrededor del location determinado.

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