Demande et réponse de géolocalisation

Requêtes de géolocalisation

Les requêtes de géolocalisation sont envoyées à l'aide de la méthode POST à l'URL suivante :

https://www.googleapis.com/geolocation/v1/geolocate?key=YOUR_API_KEY

Vous devez spécifier une clé dans la requête, incluse en tant que valeur d'un paramètre key. Un key est la clé API de votre application. Cette clé identifie votre application à des fins de gestion des quotas. Découvrez comment obtenir une clé.

Corps de la requête

Le corps de la requête doit être mis en forme en JSON. Si le corps de la requête n'est pas inclus, les résultats sont renvoyés en fonction de l'adresse IP de l'emplacement de la requête. Sauf indication contraire, les champs suivants sont acceptés et tous les champs sont facultatifs:

Champ Type JSON Description Remarques
homeMobileCountryCode number (uint32) Mobile country code (MCC) pour le réseau domicile de l'appareil. Compatible pour radioType gsm (par défaut), wcdma, lte et nr ; non utilisé pour cdma.
Plage valide: 0-999.
homeMobileNetworkCode number (uint32) Code de réseau mobile pour le réseau domicile de l'appareil. Il s'agit du numéro MNC pour GSM, WCDMA, LTE et NR.
CDMA utilise l'ID système (SID).
Plage valide pour MNC: 0–999.
Plage valide pour le SID: 0–32767.
radioType string Type du réseau de téléphonie mobile. Les valeurs acceptées sont gsm, cdma, wcdma, lte et nr. Bien que ce champ soit facultatif, il devrait toujours être inclus si le type de case d'option est connu du client.
Si le champ est omis, la valeur par défaut de l'API Geolocation est gsm, ce qui générera des résultats non valides ou nuls si le type de case d'option supposé est incorrect.
carrier string Nom de l'opérateur.
considerIp boolean Spécifie si la géolocalisation IP doit être utilisée si les signaux du Wi-Fi et des antennes-relais de téléphonie mobile sont manquants, vides ou insuffisants pour estimer la position de l'appareil. La valeur par défaut est true. Définissez considerIp sur false pour empêcher le basculement.
cellTowers array Tableau d'objets antenne-relais. Consultez la section Objets antenne-relais ci-dessous.
wifiAccessPoints array Tableau d'objets point d'accès Wi-Fi. Consultez la section Objets de point d'accès Wi-Fi ci-dessous.

Vous trouverez ci-dessous un exemple de corps de requête pour l'API 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.
  ]
}

Objets antenne-relais

Le tableau cellTowers du corps de la requête contient zéro ou plusieurs objets antenne-relais.

Champ Type JSON Description Remarques
cellId number (uint32) Identifiant cellulaire unique. Obligatoire pour radioType gsm (par défaut), cdma, wcdma et lte ; refusé pour nr.
Consultez la section Calcul de l'ID de cellule ci-dessous, qui répertorie également les plages de valeurs valides pour chaque type de case d'option.
newRadioCellId number (uint64) Identifiant unique de la cellule NR (5G). Obligatoire pour radioType nr ; rejected pour les autres types.
Consultez la section Calcul de newRadioCellId ci-dessous, qui répertorie également la plage de valeurs valides pour le champ.
locationAreaCode number (uint32) Indicatif de lieu (LAC, Location Area Code) pour les réseaux GSM et WCDMA.
ID de réseau (NID) pour les réseaux CDMA.
Indicatif de suivi (TAC, Tracking Area Code) des réseaux LTE et NR.
Obligatoire pour radioType gsm (par défaut) et cdma, facultatif pour les autres valeurs.
Plage valide avec gsm, cdma, wcdma et lte: de 0 à 65 535.
Plage valide avec nr: 0 à 16777215.
mobileCountryCode number (uint32) Code MCC (Mobile Country Code) de l'antenne-relais. Obligatoire pour radioType gsm (par défaut), wcdma, lte et nr ; non utilisé pour cdma.
Plage valide: 0-999.
mobileNetworkCode number (uint32) Code de réseau mobile de l'antenne-relais. Il s'agit du numéro MNC pour GSM, WCDMA, LTE et NR.
CDMA utilise l'ID système (SID).
Obligatoire.
Plage valide pour le MNC: 0 à 999.
Plage valide pour le SID: 0–32767.

Les champs facultatifs suivants ne sont pas utilisés, mais peuvent être inclus si des valeurs sont disponibles.

Champ Type JSON Description Remarques
age number (uint32) Temps écoulé en millisecondes depuis que cette cellule est la cellule principale. Si l'âge est égal à 0, cellId ou newRadioCellId représente une mesure actuelle.
signalStrength number (double) Puissance du signal radio mesurée en dBm.
timingAdvance number (double) Valeur d'avance temporelle.

Calcul de cellId...

Les types de radio antérieurs au NR (5G) utilisent le champ cellId 32 bits pour transmettre l'ID de cellule du réseau à l'API Geolocation.

  • Les réseaux GSM (2G) utilisent le numéro client 16 bits tel quel. Plage valide: 0–65 535.
  • Les réseaux CDMA (2G) utilisent le code BID (Base Station ID) 16 bits tel quel. Plage valide: 0–65535.
  • Les réseaux WCDMA (3G) utilisent l'identité de cellule UTRAN/GERAN (UC-ID), qui est une valeur entière de 28 bits qui concatène l'identifiant RNN (Radio Network Controller Identifier) 12 bits et l'ID de cellule 16 bits (CID).
    Formule: rnc_id << 16 | cid.
    Plage valide: 0-268435455.
    Remarque:Si vous ne spécifiez que la valeur de l'ID de cellule 16 bits dans les réseaux WCDMA, le résultat sera incorrect ou nul.
  • Les réseaux LTE (4G) utilisent l'E-UTRAN Cell Identity (ECI), qui est une valeur entière de 28 bits qui concatène l'identifiant eNBId (eNBId) du nœud E-UTRAN 20 bits et l'ID de cellule 8 bits (CID).
    Formule: enb_id << 8 | cid.
    Plage valide: 0-268435455.
    Remarque:Si vous spécifiez uniquement la valeur de l'ID de cellule sur 8 bits dans les réseaux LTE, le résultat sera incorrect ou nul.

Si vous placez des valeurs en dehors de ces plages dans la requête API, cela peut entraîner un comportement indéfini. L'API, à la discrétion de Google, peut tronquer le nombre pour qu'il rentre dans la plage documentée, inférer une correction du radioType ou renvoyer un résultat NOT_FOUND sans aucun indicateur dans la réponse.

Vous trouverez ci-dessous un exemple d'objet d'antenne-relais LTE.

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

Calcul de newRadioCellId...

Les réseaux plus récents, dont les ID de cellule sont supérieurs à 32 bits, utilisent le champ newRadioCellId 64 bits pour transmettre l'ID de cellule du réseau à l'API Geolocation.

  • Les réseaux NR (5G) utilisent la nouvelle technologie NCI (New Radio Cell Identity) 36 bits en l'état.
    Plage valide: 0–68719476735.

Vous trouverez ci-dessous un exemple d'objet antenne-relais NR.

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

Objets point d'accès Wi-Fi

Le tableau wifiAccessPoints du corps de la requête doit contenir au moins deux objets de point d'accès Wi-Fi. macAddress est obligatoire. Tous les autres champs sont facultatifs.

Champ Type JSON Description Remarques
macAddress string Adresse MAC du nœud Wi-Fi. Il est généralement appelé adresse BSS, BSSID ou MAC. Obligatoire.Chaîne hexadécimale séparée par des deux-points (:).
Seules les adresses MAC administrées universellement peuvent être trouvées via l'API. D'autres adresses MAC sont supprimées en mode silencieux, ce qui peut entraîner le vide d'une requête API. Pour en savoir plus, consultez Supprimer les points d'accès Wifi inutiles.
signalStrength number (double) Puissance actuelle du signal, mesurée en dBm. Pour les points d'accès Wi-Fi, les valeurs dBm sont généralement inférieures ou égales à -35, et comprises entre -128 et -10 dBm. Veillez à inclure le signe moins.
age number (uint32) Temps écoulé en millisecondes depuis que ce point d'accès a été détecté.
channel number (uint32) Canal sur lequel le client communique avec le point d'accès.
signalToNoiseRatio number (double) Rapport signal/bruit actuel mesuré en dB.

Voici un exemple d'objet point d'accès Wi-Fi.

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

Exemples de requêtes

Si vous souhaitez essayer l'API Geolocation avec des exemples de données, enregistrez le fichier JSON suivant dans un fichier:

{
  "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
    }
  ]
}

Vous pouvez ensuite exécuter votre requête à partir de la ligne de commande à l'aide de la commande cURL:

$ curl -d @your_filename.json -H "Content-Type: application/json" -i "https://www.googleapis.com/geolocation/v1/geolocate?key=YOUR_API_KEY"

La réponse pour les adresses MAC précédentes se présente comme suit:

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

Suppression des points d'accès Wi-Fi inutilisés

La suppression des objets de point d'accès Wi-Fi avec des macAddress administrés localement peut améliorer le taux de réussite des appels d'API Geolocation qui utilisent le Wi-Fi en entrée. Si, après le filtrage, il est possible de déterminer qu'un appel d'API Geolocation n'aboutit pas, vous pouvez appliquer des mesures d'atténuation, telles que l'utilisation d'anciens signaux de localisation ou de points d'accès Wi-Fi présentant des signaux plus faibles. Cette approche constitue un compromis entre le besoin d'une estimation de position pour votre application et ses exigences de précision et de rappel. Les techniques de filtrage suivantes montrent comment filtrer les entrées, mais n'indiquent pas les mesures d'atténuation que vous pouvez choisir d'appliquer en tant qu'ingénieur d'applications.

Les adresses MAC administrées localement ne sont pas des signaux d'emplacement utiles pour l'API et sont supprimées en mode silencieux des requêtes. Vous pouvez supprimer ces adresses MAC en vous assurant que le deuxième bit le moins significatif de l'octet le plus significatif de macAddress est 0 (par exemple, 1 bit représenté par 2 dans 02:00:00:00:00:00). L'adresse MAC de diffusion (FF:FF:FF:FF:FF:FF) est un exemple d'adresse MAC qui serait utilement exclue par ce filtre.

La plage d'adresses MAC comprise entre 00:00:5E:00:00:00 et 00:00:5E:FF:FF:FF est réservée à l'IANA et souvent utilisée pour la gestion de réseau et les fonctions de multidiffusion qui empêchent leur utilisation en tant que signal de localisation. Vous devez également supprimer ces adresses MAC des entrées de l'API.

Par exemple, les adresses MAC utilisables pour la géolocalisation peuvent être collectées à partir d'un tableau de chaînes macAddress nommé 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 vous utilisez ce filtre, il ne reste que 1c:34:56:78:9a:bc dans la liste. Comme cette liste contient moins de deux adresses MAC Wi-Fi, la requête n'aboutit pas, et une réponse HTTP 404 (notFound) est renvoyée.

Réponses de géolocalisation

Une requête de géolocalisation réussie renvoie une réponse au format JSON définissant un emplacement et un rayon.

  • location: coordonnées de latitude et de longitude estimées de l'utilisateur, en degrés. Contient un sous-champ lat et un sous-champ lng.
  • accuracy: précision de la position estimée, en mètres. Représente le rayon d'un cercle autour de la valeur location donnée.
{
  "location": {
    "lat": 37.421875199999995,
    "lng": -122.0851173
  },
  "accuracy": 120
}