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 key parámetro. Una key es la clave de API de tu aplicación. Esta clave identifica tu aplicación para la administración de cuotas management. 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 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:

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

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

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

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á. Intervalo válido: 0–65535.
• Las redes CDMA (2G) usan el ID de estación base (BID) de 16 bits tal como está. Intervalo válido: 0–65535.
• Las redes WCDMA (3G) usan la identidad de celda 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.
  Intervalo válido: 0–268435455.
  Nota: Si se especifica solo el valor del ID de celda de 16 bits en las redes WCDMA, se obtendrán resultados incorrectos o cero.
• 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 E-UTRAN (eNBId) de 20 bits y el ID de celda (CID) de 8 bits.
  Fórmula: enb_id << 8 | cid.
  Intervalo válido: 0–268435455.
  Nota: Si se especifica solo el valor del ID de celda de 8 bits en las redes LTE, se obtendrán resultados incorrectos o cero.

Si colocas valores fuera de estos intervalos en la solicitud de 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 intervalo documentado, inferir una corrección al radioType o mostrar un resultado NOT_FOUND sin ningún indicador en la respuesta.

A continuación, se muestra un ejemplo de un objeto de torre 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
}

Cómo calcular newRadioCellId

Las redes más nuevas, cuyos IDs de celda son más largos que 32 bits, usan el campo de 64 bits newRadioCellId 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á.
  Intervalo válido: 0–68719476735.

A continuación, se muestra un ejemplo de un objeto de torre 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 WiFi que representen dispositivos de punto de acceso estacionarios 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 un objeto de punto de acceso WiFi, que forma parte del cuerpo de la solicitud, es mostrado a continuación.

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

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

Cómo descartar puntos de acceso WiFi no utilizados

Quitar objetos de punto de acceso WiFi con macAddresses que sean una dirección de transmisión (FF:FF:FF:FF:FF:FF) o que estén reservadas por la IANA puede mejorar la tasa de éxito de las llamadas a la API de Geolocation que usan WiFi como entrada. Si, después de filtrar, se puede determinar que una llamada a la API de Geolocation no tendrá éxito, se pueden usar mitigaciones, como usar señales de ubicación más antiguas o APs de Wi-Fi con señales 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 elegir aplicar.

El intervalo 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 transmisión de multidifusión, lo que impide su uso como señal de ubicación. También debes quitar estas direcciones MAC de las entradas a la API.

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

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

Respuestas a solicitudes de geolocalización

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

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

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

La API muestra una ubicación y un radio de precisión según las señales de entrada. Si bien la API puede mostrar una ubicación muy precisa, la precisión 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 WiFi: Si la solicitud incluye dos o más wifiAccessPoints, el radio de precisión que se muestra suele ser de unos 20 metros. La precisión mejora con la cantidad de puntos de acceso y señales más fuertes (medidas en dBm), con intensidades de señal que suelen oscilar entre -100 y -20 dBm.
• Torres celulares: 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 celular, la intensidad de la señal y la densidad de la red:
  • Las macroceldas (el tipo más común, que se usa para la cobertura de área amplia) proporcionan una precisión más baja. El radio suele estar en el rango de cientos de metros y puede ser de varios miles de metros en áreas con cobertura de torre celular dispersa. En el caso de las macroceldas, no es común lograr un radio de precisión inferior a 100 metros. La precisión suele ser mayor para las torres celulares con señales fuertes. Las señales fuertes suelen ser típicamente > -110 dBm para LTE (intervalo de señal de -140 a -55 dBm), > -100 dBm para WCDMA (intervalo de señal de -111 a -53 dBm), > -100 dBm para CDMA (intervalo de señal de -120 a -40 dBm) y > -80 dBm para GSM (intervalo de señal de -121 a -1 dBm).
  • Las celdas pequeñas (p.ej., femtoceldas, picoceldas o repetidores interiores) proporcionan la ubicación más precisa basada en celdas, con radios de precisión que pueden estar en el rango de 10 a 30 metros.
• Geolocalización de IP: Si considerIp es true y no se pueden geolocalizar señales de Wi-Fi ni de torres celulares, la API estima la ubicación según la dirección IP de la solicitud. Este método proporciona la precisión más baja, 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.