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. Esa clave identifica tu aplicación a los fines de la administración de la cuota. 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) para la red local del dispositivo. | Se admite para radioType gsm (predeterminado), wcdma , lte y nr ; no se usa para cdma .Rango válido: De 0 a 999. |
homeMobileNetworkCode |
number (uint32 ) |
El código de red móvil de la red doméstica del dispositivo.
Es decir, 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 . |
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 cero si el tipo de radio supuesto es
incorrecto. |
carrier |
string |
Nombre del proveedor. | |
considerIp |
boolean |
Especifica si se debe volver a la geolocalización de IP si faltan señales de Wi-Fi y torres celulares, están vacías o no son suficientes para estimar la ubicación del dispositivo. | La configuración predeterminada es true . Establece considerIp en false para evitar el regreso a la IP. |
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 WiFi 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 celulares.
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álculo de lacellId 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 ) |
El código de área del sitio (LAC) para redes GSM y WCDMA. Es el ID de red (NID) de las redes CDMA. El código de área de seguimiento (TAC) para 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 de país móvil (MCC) de la torre celular. | Obligatorio para radioType gsm (predeterminado), wcdma ,
lte y nr ; no se usa para cdma .Rango válido: De 0 a 999. |
mobileNetworkCode |
number (uint32 ) |
El código de red móvil de la torre celular.
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: de 0 a 32,767. |
Los siguientes campos opcionales no se utilizan, 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 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 tiempo. |
Calculando cellId
Los tipos de radio anteriores a NR (5G) usan el campo cellId
de 32 bits para pasar el ID de la celda de red a la API de Geolocation.
- Las redes GSM (2G) utilizan el ID de celular de 16 bits (CID) tal como está. Rango válido: 0–65535.
- 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 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 del celular 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 celular de 16 bits en las redes WCDMA, se obtienen resultados incorrectos o cero. - Las redes LTE (4G) usan la identificación celular 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 la celda de 8 bits (CID).
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 redes LTE, el resultado será incorrecto 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 incluye 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 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 nueva identidad de la celda de radio (NCI) de 36 bits tal como está.
Rango válido: de 0 a 68719476735.
A continuación, se incluye un ejemplo de objeto de torre de telefonía 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 WiFi 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 |
Es 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 ubicar direcciones MAC administradas universalmente 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. | Para los puntos de acceso Wi-Fi, los valores de dBm son normalmente de -35 dBm 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": "f0:d5:bf:fd:12:ae", "signalStrength": -43, "signalToNoiseRatio": 0, "channel": 11, "age": 0 }
Ejemplos de solicitudes
Si quieres probar la API de Geolocation con datos de ejemplo, 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 }
Cómo quitar puntos de acceso WiFi que no se usan
Quitar los objetos de punto de acceso Wi-Fi con macAddress
que se locally-administered 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 tendrá é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 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. En las siguientes técnicas de filtrado, se demuestra 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 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 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 funciones de administración de red y 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 que se pueden usar para la ubicación geográfica se pueden recopilar de un array de cadenas macAddress
llamadas macs
:
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")));
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')]
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 quede 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 ubicación geográfica 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 subcampolat
y unolng
.accuracy
: Es la precisión de la ubicación estimada en metros. Esto representa el radio de un círculo alrededor dellocation
determinado.
{ "location": { "lat": 37.421875199999995, "lng": -122.0851173 }, "accuracy": 120 }