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 una Parámetro key. Un key es el ID de tu aplicación Clave de API. Esta clave identifica tu aplicación a los fines de la cuota y administración de posturas. 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 en función de la dirección IP de la ubicación de la solicitud. Los siguientes campos y todos los campos 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. Compatible con radioType gsm (predeterminado), wcdma, lte y nr; no se usa para cdma.
Rango válido: de 0 a 999.
homeMobileNetworkCode number (uint32) Indica el código de red móvil de la red particular del dispositivo. Es el MNC para GSM, WCDMA, LTE y NR.
CDMA utiliza el ID del sistema (SID).
Rango válido de MNC: 0-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, siempre debe incluirse si el tipo de radio es que conoce el cliente.
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 ubicación geográfica de IP en caso de que falten señales de Wi-Fi y de torres de telefonía celular. vacía, o bien no es suficiente para calcular la ubicación del dispositivo. La configuración predeterminada es true. Establecer considerIp en false para evitar el resguardo.
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 Wi-Fi. a continuación.

A continuación, se muestra un ejemplo del cuerpo de la 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. 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; rechazada por nr.
Consulta la sección Calcular el ID de la celda a continuación, en la que también se enumera 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. rechazada por otros de tipos de datos.
Consulta la sección Calcular newRadioCellId a continuación. que también enumera el rango de valores válido para el campo.
locationAreaCode number (uint32) El código de área de ubicación (LAC) para redes GSM y WCDMA.
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: 0–16777215.
mobileCountryCode number (uint32) El 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: 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 utiliza el ID del sistema (SID).
Obligatorio.
Rango válido de MNC: 0-999.
Rango válido para el SID: 0–32,767.

Los siguientes campos opcionales no se utilizan, pero se pueden incluir si los valores se 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 un valor de medición.
signalStrength number (double) Potencia de la señal de radio medida en dBm.
timingAdvance number (double) El adelanto de plazo valor.

Calculando cellId

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

  • Las redes GSM (2G) utilizan el ID de celular de 16 bits (CID) tal como están. 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) utilizan la identidad celular UTRAN/GERAN (UC-ID), que es un número entero de 28 bits valor que concatena el identificador del controlador de red de radio (RNC-ID) de 12 bits y el de 16 bits ID de celular (CID).
    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 obtiene son incorrectos o no hay resultados.
  • Las redes LTE (4G) utilizan la identidad celular E-UTRAN (ECI), que es un valor entero de 28 bits concatenando el identificador E-UTRAN Node B de 20 bits (eNBId) y el ID de celular 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 celular de 8 bits en las redes LTE, se obtiene lo siguiente: son incorrectos o no hay resultados.

Colocar valores fuera de estos rangos en la solicitud a la API puede dar como resultado un comportamiento indefinido. La API, a discreción de Google, podría truncar el número para que se ajuste al rango documentado, inferir un corrección de radioType o mostrar un resultado de NOT_FOUND sin ningún indicador clave 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
    }
  ]
}

Cálculo newRadioCellId

Las redes más nuevas, cuyos ID de celdas son más largos de 32 bits, usan el de 64 bits. Campo newRadioCellId para pasar el ID de celda de red a API de Geolocation.

  • Las redes NR (5G) usan la New Radio Cell Identity (NCI) de 36 bits tal como está.
    Rango válido: 0–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. El campo macAddress es obligatorio. todas otros 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. String hexadecimal separada por dos puntos (:).
Solo administrados por todo el mundo Las direcciones MAC se pueden ubicar a través de la API. Las demás direcciones MAC se descarta sin aviso y puede hacer que una solicitud a la API sea efectiva vacío. Para obtener más información, consulta Cómo abandonar un acceso Wi-Fi inútil puntos.
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 un 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 realiza 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
}

Olvidar puntos de acceso Wi-Fi sin usar

Quitar objetos de punto de acceso Wi-Fi con macAddress que se 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, luego del filtrado, se puede determinar que una llamada a la API de Geolocation no tienen éxito, las mitigaciones, como el uso de señales de ubicación más antiguas o puntos de acceso de Wi-Fi con se pueden usar 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 podrías, ingeniero, elige aplicar.

Las direcciones MAC administradas de forma local no son indicadores de ubicación útiles para la API y se eliminan de las solicitudes de forma silenciosa. Puedes quitar esas direcciones MAC garantizando que la segunda parte menos significativa de la El byte más importante de macAddress es 0, p.ej., el 1 bit 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 sería este filtro excluye útilmente.

El rango de direcciones MAC entre 00:00:5E:00:00:00 y 00:00:5E:FF:FF:FF son reservado para IANA y, a menudo, se usa para la administración de redes y funciones de multidifusión lo que excluye 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 pueden recopilarse desde una 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');
    

El uso de este filtro da como resultado solo 1c:34:56:78:9a:bc restantes en la lista. Debido a que esta lista tiene menos de 2 direcciones MAC de Wi-Fi, el la solicitud no tendrá éxito y se generará una solicitud (notFound) respuesta.

Respuestas a solicitudes de geolocalización

Una solicitud de ubicación geográfica exitosa muestra una respuesta con formato JSON definir una ubicación y un radio.

  • location: La latitud y longitud estimadas del usuario coordenadas, 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 del objeto location
{
  "location": {
    "lat": 37.421875199999995,
    "lng": -122.0851173
  },
  "accuracy": 120
}