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. key es la clave de API de tu aplicación. Esta clave identifica tu aplicación para administrar la cuota. Obtén 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:

A continuación, se muestra un ejemplo de cuerpo de solicitud a la API de Geolocation.

{
  "homeMobileCountryCode": 310,
  "homeMobileNetworkCode": 410,
  "radioType": "lte",
  "carrier": "Vodafone",
  "considerIp": true,
  "cellTowers": [
    // See the Cell Tower Objects section below.
  ],
  "wifiAccessPoints": [
    // See the WiFi Access Point Objects section below.
  ]
}

Objetos de torres de telefonía celular

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

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

Calculando 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 el identificador de celda 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 celda (CID) de 16 bits.
  Fórmula: rnc_id << 16 | cid.
  Intervalo válido: 0-268435455.
  Nota: Si especificas solo el valor del 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 de 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 especificas el valor del ID de celda de 8 bits en las redes LTE, se producirán resultados incorrectos o nulos.

Si se colocan valores fuera de estos rangos en la solicitud a la API, es posible que se produzca 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 el radioType o devolver un resultado NOT_FOUND sin ningún indicador en la respuesta.

A continuación, se muestra un ejemplo de un objeto de torre de telefonía celular LTE, que forma parte del cuerpo de la solicitud.

{
  ...

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

La respuesta a la solicitud anterior se ve de la siguiente manera:

{
  "location": {
    "lat": 37.7801129,
    "lng": -122.4168229
  },
  "accuracy": 180.052
}

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 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á.
  Rango válido: 0-68719476735.

A continuación, se muestra un ejemplo de un objeto de torre de telefonía celular NR, que forma parte del cuerpo de la solicitud.

{
  ...

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

La respuesta a la solicitud anterior se ve de la siguiente manera:

{
  "location": {
    "lat": 37.7646157,
    "lng": -122.4127361
  },
  "accuracy": 1458.5570522410717
}

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 que representen dispositivos de punto de acceso fijos físicamente distintos. El campo macAddress es obligatorio. Todos los demás campos son opcionales. El servicio ignora los puntos de acceso que se mueven, como los de aviones y trenes.

A continuación, se muestra un ejemplo de objeto de punto de acceso Wi-Fi, que forma parte del cuerpo de la solicitud.

{
  ...
  
  "macAddress": "f0:d5:bf:fd:12:ae",
  "signalStrength": -43,
  "signalToNoiseRatio": 0,
  "channel": 11,
  "age": 0
}

La respuesta a la solicitud anterior se ve de la siguiente manera:

{
  "location": {
    "lat": 37.7801129,
    "lng": -122.4168229
  },
  "accuracy": 180.052
}

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": "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 para las direcciones MAC anteriores se ve de la siguiente manera:

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

Se descartan los puntos de acceso Wi-Fi que no se usan

Quitar los objetos de punto de acceso Wi-Fi con macAddress que sean una dirección de broadcast (FF:FF:FF:FF:FF:FF) o que estén reservados por la IANA 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ía correctamente, se pueden usar mitigaciones, como usar indicadores de ubicación más antiguos o APs de Wi-Fi con indicadores más débiles. Este enfoque es un equilibrio entre la necesidad de tu aplicación de obtener 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, como ingeniero de aplicaciones, puedes aplicar.

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 multidifusión, 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 ubicación geográfica se pueden recopilar de un array de cadenas macAddress llamadas macs:

String[] macs = {"ff:ff:ff:ff:ff:ff", "1c:34:56:78:9a:bc", "00:00:5e:00:00:01"};
ArrayList<String> _macs = new ArrayList<>(Arrays.asList(macs));
_macs.removeIf(m -> !(!m.toUpperCase().equals("FF:FF:FF:FF:FF:FF")
                      && !m.substring(0, 8).toUpperCase().equals("00:00:5E")));
    

macs = ['ff:ff:ff:ff:ff:ff', '1c:34:56:78:9a:bc', '00:00:5e:00:00:01']
macs = [m for m in macs if (m.upper() != "FF:FF:FF:FF:FF:FF" and m[:8].upper() != '00:00:5E')]
    

macs = ['ff:ff:ff:ff:ff:ff', '1c:34:56:78:9a:bc', '00:00:5e:00:00:01'];
macs = macs.filter(m => m.toUpperCase() !== "FF:FF:FF:FF:FF:FF"
                        && 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ía correctamente y se devolvería una respuesta HTTP 404 (notFound).

Respuestas a solicitudes de geolocalización

Una solicitud de ubicación geográfica exitosa devuelve una respuesta con 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
}

La API devuelve una ubicación y un radio de exactitud según los indicadores de entrada. Si bien la API puede devolver una ubicación muy precisa, la exactitud puede variar según la fuente, la cantidad, la densidad y la intensidad de las señales disponibles. Por lo general, puedes esperar los siguientes radios de precisión:

• Puntos de acceso Wi-Fi: Si la solicitud incluye dos o más objetos wifiAccessPoints, el radio de exactitud que se muestra suele ser de alrededor de 20 metros. La precisión mejora con la cantidad de puntos de acceso y las señales más fuertes (medidas en dBm), con intensidades de señal que suelen variar entre -100 y -20 dBm.
• Torres de telefonía celular: Si la información de Wi-Fi no está disponible o es insuficiente, la API usa cellTowers para la ubicación. La precisión varía significativamente según el tipo de torre de telefonía celular, la intensidad de la señal y la densidad de la red:
  • Las celdas macro (el tipo más común, que se usa para la cobertura de áreas amplias) proporcionan una precisión más baja. Por lo general, el radio se encuentra en el rango de cientos de metros y puede ser de hasta varios miles de metros en áreas con cobertura de torres de telefonía celular dispersa. En el caso de las macroceldas, no es común lograr un radio de precisión inferior a 100 metros. Por lo general, la precisión es mayor para las torres de telefonía celular con señales fuertes. Las señales fuertes suelen ser > -110 dBm para LTE (rango de señal de -140 a -55 dBm), > -100 dBm para WCDMA (rango de señal de -111 a -53 dBm), > -100 dBm para CDMA (rango de señal de -120 a -40 dBm) y > -80 dBm para GSM (rango de señal de -121 a -1 dBm).
  • Las celdas pequeñas (p.ej., femtoceldas, picoceldas o repetidores de interiores) proporcionan la ubicación basada en celdas más precisa, con radios de precisión que pueden estar en el rango de 10 a 30 metros.
• Ubicación geográfica de IP: Si considerIp es true y no se puede determinar la ubicación geográfica de ninguna señal de Wi-Fi ni de torre de telefonía celular, la API estima la ubicación en función de la dirección IP de la solicitud. Este método proporciona la menor exactitud, con radios que pueden ser de miles de metros. Consulta ¿Por qué el radio de precisión es muy grande? en la guía de solución de problemas.