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 votre requête, incluse en tant que valeur d'un paramètre key. key correspond à la clé API de votre application. Cette clé permet d'identifier votre application pour la 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. Tous les champs 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é pour `cdma`. Plage valide : 0 à 999.
`homeMobileNetworkCode`	`number` (`uint32`)	Code réseau mobile du réseau domicile de l'appareil. Il s'agit du MNC pour GSM, WCDMA, LTE et NR. CDMA utilise l'ID système (SID).	La plage de valeurs autorisée pour le code MNC est comprise entre 0 et 999. La plage de valeurs valides pour le SID est comprise entre 0 et 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 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îne 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 s'il faut revenir à la géolocalisation par adresse IP 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 retour à la version précédente.
`cellTowers`	`array`	Tableau d'objets antenne-relais.	Consultez la section Objets de type "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.

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 tour 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 liste également les plages de valeurs valides pour chaque type de 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 liste é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 de valeurs valides 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 du MNC pour GSM, WCDMA, LTE et NR. CDMA utilise l'ID système (SID).	Obligatoire. La plage de valeurs valides pour le code MNC est comprise entre 0 et 999. La plage de valeurs valides pour le SID est comprise entre 0 et 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 défini sur 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'avance temporelle.

Calcul de `cellId`

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

Les réseaux GSM (2G) utilisent l'ID de cellule (CID) de 16 bits tel quel. Plage valide : 0 à 65 535.
Les réseaux CDMA (2G) utilisent l'ID de station de base (BID) de 16 bits tel quel. Plage valide : 0 à 65 535.
Les réseaux WCDMA (3G) utilisent l'identifiant de cellule UTRAN/GERAN (UC-ID), qui est une valeur entière de 28 bits concaténant l'identifiant de 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 : de 0 à 268435455.
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 : de 0 à 268435455.
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, cela peut entraîner un comportement indéfini. L'API peut, à la discrétion de Google, tronquer le nombre pour qu'il s'inscrive dans la plage documentée, déduire 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 de tour de téléphonie mobile LTE.

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

Calcul en cours `newRadioCellId`

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

Les réseaux NR (5G) utilisent l'identité de cellule New Radio (NCI) de 36 bits telle quelle.
Plage valide : de 0 à 68 719 476 735.

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, tandis que 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'un BSS, d'un BSSID ou d'une adresse MAC.	Obligatoire.Chaîne hexadécimale séparée par des deux-points (`:`). Seules les adresses MAC administrées universellement peuvent être localisées via l'API. Les autres adresses MAC sont ignorées et peuvent entraîner une requête API vide. Pour en savoir plus, consultez Supprimer les 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 dBm sont généralement inférieures ou égales à -35 et comprises entre -128 et -10 dBm. Veillez à inclure le signe moins. Pour les valeurs supérieures à -10 dBm, l'API renvoie `NOT FOUND`.
`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 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
}

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

La suppression des objets de point d'accès Wi-Fi avec des macAddresses administrées 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 déterminé qu'un appel à l'API Geolocation ne réussira pas, des mesures d'atténuation peuvent être utilisées, comme l'utilisation d'anciens signaux de localisation ou de points d'accès Wi-Fi avec des signaux plus faibles. Cette approche constitue un compromis entre le besoin de votre application d'obtenir une estimation de la position et ses exigences en termes de précision et de rappel. Les techniques de filtrage suivantes montrent comment filtrer les entrées, mais ne présentent pas les atténuations 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 silencieusement 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 souvent utilisée pour la gestion du réseau et les fonctions de multidiffusion, ce qui empêche de les utiliser 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');

Si vous utilisez ce filtre, il ne restera que 1c:34:56:78:9a:bc éléments dans la liste. Étant donné que cette liste contient moins de deux adresses MAC Wi-Fi, la requête ne sera pas traité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 une position 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. Il s'agit du rayon d'un cercle autour du location donné.

{
  "location": {
    "lat": 37.421875199999995,
    "lng": -122.0851173
  },
  "accuracy": 120
}