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 votre 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. Les champs suivants sont acceptés et tous sont facultatifs, sauf indication contraire:

Champ Type JSON Description Remarques
homeMobileCountryCode number (uint32) Mobile country code (MCC) du réseau d'origine de l'appareil. Compatible avec radioType gsm (par défaut), wcdma, lte et nr. Non utilisé avec cdma.
Plage valide: 0 à 999.
homeMobileNetworkCode number (uint32) Code du réseau mobile du réseau domestique de l'appareil. Il s'agit de l'opérateur mobile pour GSM, WCDMA, LTE et NR.
CDMA utilise l'ID système (SID).		 Plage valide pour le code MNC: 0 à 999.
Plage valide pour le SID: 0 à 32 767.
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 doit toujours être inclus si le type de radio est connu par le client.
Si le champ est omis, l'API Geolocation utilise par défaut gsm, ce qui entraînera des résultats non valides ou nuls si le type de radio supposé est incorrect.
carrier string Nom de l'opérateur.
considerIp boolean Indique si la géolocalisation par adresse IP doit être utilisée si les signaux Wi-Fi et des antennes-relais 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 éviter le remplacement.
cellTowers array Tableau d'objets antenne-relais. Consultez la section Objets de tours de téléphonie mobile 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.

Un exemple de corps de requête de l'API Geolocation est présenté ci-dessous.

{
  "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 de tours de téléphonie mobile.

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 Calculer cellId ci-dessous, qui indique également les plages de valeurs valides pour chaque type de bouton radio.
newRadioCellId number (uint64) Identifiant unique de la cellule NR (5G). Obligatoire pour radioType nr ; refusé pour les autres types.
Consultez la section Calculer newRadioCellId ci-dessous, qui indique également la plage de valeurs valides pour le champ.
locationAreaCode number (uint32) Code de zone de localisation (LAC) pour les réseaux GSM et WCDMA.
ID de réseau (NID) pour les réseaux CDMA.
Code de zone de suivi (TAC) pour les 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: 0 à 65 535.
Plage valide avec nr: 0 à 16777215.
mobileCountryCode number (uint32) Mobile country code (MCC) 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 de l'opérateur mobile pour GSM, WCDMA, LTE et NR.
CDMA utilise l'ID système (SID).		 Obligatoire.
Plage valide pour le code pays de l'opérateur: 0 à 999.
Plage valide pour le SID: 0 à 32 767.

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 de l'avancement temporel.

Calcul de cellId

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

  • Les réseaux GSM (2G) utilisent l'ID de cellule (CID) de 16 bits tel quel. Plage de valeurs valide: 0 à 65 535.
  • Les réseaux CDMA (2G) utilisent l'ID de la station de base (BID) de 16 bits tel quel. Plage valide: 0 à 65 535.
  • Les réseaux WCDMA (3G) utilisent l'identité de cellule UTRAN/GERAN (UC-ID), qui est une valeur entière de 28 bits concatenant l'identifiant du contrôleur de réseau radio (RNC-ID) de 12 bits et l'identifiant de cellule (CID) de 16 bits.
    Formule: rnc_id << 16 | cid
     Plage valide: 0 à 268 435 455.
    Remarque:Si vous ne spécifiez que la valeur de l'ID de cellule de 16 bits dans les réseaux WCDMA, les résultats seront incorrects ou nuls.
  • Les réseaux LTE (4G) utilisent l'identité de cellule E-UTRAN (ECI), qui est une valeur entière de 28 bits concaténant l'identifiant de nœud B E-UTRAN (eNBId) de 20 bits et l'ID de cellule (CID) de 8 bits.
    Formule: enb_id << 8 | cid
     Plage valide: 0 à 268 435 455.
    Remarque:Si vous ne spécifiez que la valeur de l'ID de cellule de 8 bits dans les réseaux LTE, les résultats seront incorrects ou nuls.

Si vous placez des valeurs en dehors de ces plages dans la requête API, un comportement non défini peut se produire. L'API peut, à la discrétion de Google, tronquer le nombre pour qu'il s'adapte à la plage documentée, inférer une correction de l'radioType ou renvoyer un résultat NOT_FOUND sans indicateur dans la réponse.

Vous trouverez ci-dessous un exemple d'objet de tour de téléphonie mobile 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 plus longs que 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 l'identité de cellule radio nouvelle génération (NCI) de 36 bits telle quelle.
    Marge de validité: 0 à 68719476735.

Vous trouverez ci-dessous un exemple d'objet de tour de téléphonie mobile 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 représentant des appareils de point d'accès physiquement distincts. macAddress est obligatoire ; tous les autres champs sont facultatifs.

Champ Type JSON Description Remarques
macAddress string Adresse MAC du nœud Wi-Fi. Il s'agit généralement d'une adresse BSS, BSSID ou MAC. Obligatoire : chaîne hexadécimale séparée par deux-points (:).
Seules les adresses MAC administrées universellement peuvent être localisées via l'API. Les autres adresses MAC sont supprimées de manière silencieuse et peuvent entraîner une requête API vide. Pour en savoir plus, consultez Supprimer des points d'accès Wi-Fi inutiles.
signalStrength number (double) Puissance actuelle du signal, mesurée en dBm. Pour les points d'accès Wi-Fi, les valeurs en dBm sont généralement de -35 ou moins, et varient de -128 à -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 sur 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 code 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 utiliser cURL pour envoyer votre requête à partir de la ligne de commande:

$ 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
}

Supprimer les points d'accès Wi-Fi inutilisés

Supprimer les 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 comme entrée. Si, après filtrage, il est possible de déterminer qu'un appel d'API de géolocalisation ne réussira pas, des mesures d'atténuation telles que l'utilisation de signaux de localisation plus anciens ou de points d'accès Wi-Fi avec des signaux plus faibles peuvent être prises. Cette approche est un compromis entre le besoin d'estimation de position de votre application et ses exigences de précision et de rappel. Les techniques de filtrage suivantes montrent comment filtrer les entrées, mais ne montrent pas les mesures d'atténuation que vous pouvez choisir d'appliquer en tant qu'ingénieur d'application.

Les adresses MAC administrées localement ne sont pas des signaux de localisation utiles pour l'API et sont supprimées de manière silencieuse 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 le bit 1 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 est souvent utilisée pour la gestion de réseau et les fonctions multicast, ce qui empêche leur utilisation comme 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');

L'utilisation de ce filtre ne laisse que 1c:34:56:78:9a:bc dans la liste. Étant donné que cette liste comporte moins de deux adresses MAC Wi-Fi, la requête ne sera pas effectuée et une réponse HTTP 404 (notFound) sera 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 l'location donné.
{
  "location": {
    "lat": 37.421875199999995,
    "lng": -122.0851173
  },
  "accuracy": 120
}