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 a los efectos de 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 devuelven 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) Es el código móvil de país (MCC) de la red principal del dispositivo. Admitido para radioType gsm (predeterminado), wcdma, lte y nr; no se usa para cdma.
Rango válido: 0 a 999.
homeMobileNetworkCode number (uint32) Es el código de red móvil de la red principal del dispositivo. Este es el MNC para GSM, WCDMA, LTE y NR.
CDMA usa el ID del sistema (SID).
El rango válido para el MNC es de 0 a 999.
El rango válido para el SID es de 0 a 32767.
radioType string El tipo de radio móvil. Los valores admitidos son gsm, cdma, wcdma, lte y nr. Si bien 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 usa gsm de forma predeterminada, lo que generará resultados no válidos o nulos si el tipo de radio supuesto es incorrecto.
carrier string Nombre del proveedor.
considerIp boolean Especifica si se debe recurrir a la geolocalización por IP si faltan las señales de Wi-Fi y de torres de telefonía celular, si están vacías o si no son suficientes para estimar la ubicación del dispositivo. La configuración predeterminada es true. Establece considerIp en false para evitar la reversión.
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 puntos de acceso Wi-Fi a continuación.

A continuación, se muestra un ejemplo del cuerpo de una 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 cellId 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ómo calcular newRadioCellId a continuación, que también enumera 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: 0 a 65535.
Rango válido con nr: de 0 a 16777215.
mobileCountryCode number (uint32) Código móvil de país (MCC) de la torre celular. Obligatorio para radioType gsm (predeterminado), wcdma, lte y nr; no se usa para cdma.
Rango válido: 0 a 999.
mobileNetworkCode number (uint32) Es 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.
El rango válido para el MNC es de 0 a 999.
El rango válido para el SID es de 0 a 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, cellId o 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 de sincronización.

Cómo calcular 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á. El rango válido es de 0 a 65535.
  • Las redes CDMA (2G) usan el ID de estación base (BID) de 16 bits tal como está. El rango válido es de 0 a 65535.
  • Las redes WCDMA (3G) usan la identidad de celda de UTRAN/GERAN (UC-ID), que es un valor 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 solo se especifica el valor de ID de celda de 16 bits en las redes WCDMA, se obtendrán resultados incorrectos o nulos.
  • Las redes LTE (4G) usan la identidad de celda E-UTRAN (ECI), que es un valor 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 solo se especifica el valor de ID de celda de 8 bits en las redes LTE, se obtendrán resultados incorrectos o nulos.

Si se colocan valores fuera de estos rangos en la solicitud de la API, se puede producir un comportamiento indefinido. A discreción de Google, la API puede truncar el número para que se ajuste al rango documentado, inferir una corrección para radioType o devolver un resultado de NOT_FOUND sin ningún indicador en la respuesta.

A continuación, se muestra un ejemplo de un objeto de torre 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 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 celda de radio nueva (NCI) de 36 bits tal como está.
    El rango válido es de 0 a 68719476735.

A continuación, se muestra un ejemplo de un 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 puntos de acceso Wi-Fi que representen dispositivos de puntos de acceso físicamente distintos. 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 de Wi-Fi. Por lo general, se denomina BSS, BSSID o dirección MAC. Obligatorio. Cadena hexadecimal separada por dos puntos (:).
Solo se pueden ubicar las direcciones MAC administradas de forma universal a través de la API. Otras direcciones MAC se descartan de forma silenciosa y pueden hacer que una solicitud a la API quede efectivamente vacía. Para obtener más información, consulta Cómo descartar 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 oscilan entre -128 y -10 dBm. Asegúrate de incluir el signo menos.
Para valores superiores a -10 dBm, la API devuelve 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 código 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 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 anteriores se ve de la siguiente manera:

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

Desconecta los puntos de acceso Wi-Fi que no se usan

Quitar objetos de puntos de acceso Wi-Fi con macAddress que son administrados 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 de filtrar, se puede determinar que una llamada a la API de Geolocation no se realizará 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 equilibrio entre la necesidad de tu aplicación de una estimación de ubicación y sus requisitos de precisión y recuperación. Las siguientes técnicas de filtrado demuestran cómo filtrar las entradas, pero no muestran las mitigaciones que tú, como ingeniero de aplicaciones, puedes optar por aplicar.

Las direcciones MAC administradas de forma local no son indicadores 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 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 manera ú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 las funciones de administración de redes y multidifusión, lo que impide 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 utilizables para la API de Geolocation se pueden recopilar a partir de un array de cadenas 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');
    

Si usas este filtro, solo quedarán 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ía correctamente y se devolvería una respuesta HTTP 404(notFound).

Respuestas a solicitudes de geolocalización

Una solicitud de geolocalización exitosa devuelve 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 del location determinado.
{
  "location": {
    "lat": 37.421875199999995,
    "lng": -122.0851173
  },
  "accuracy": 120
}