Cette page a été traduite par l'API Cloud Translation.

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": "9c:1c:12:b0:45:f1",
  "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": "94:b4:0f:fd:c1:40",
      "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.4241876,
      "lng": -122.0917381
  },
  "accuracy": 32.839
}

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
}