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. 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'accueil 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 de 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 du client. Si le champ est omis, la valeur par défaut de l'API Geolocation est `gsm`, ce qui renvoie 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`	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) des 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`)	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 de l'opérateur mobile pour GSM, WCDMA, LTE et NR. Le 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-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 dans le temps.

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 16 bits en l'état. Plage valide: 0 à 65 535.
Les réseaux CDMA (2G) utilisent l'ID de la station de base (BID) de 16 bits tel quel. Plage de valeurs valides : 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'ID 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.

Placer des valeurs en dehors de ces plages dans la requête API peut entraîner un comportement non défini. L'API, à la discrétion de Google, peut 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 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 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 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 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

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 pas les mesures d'atténuation que vous pouvez, en tant qu'ingénieur d'application, choisir d'appliquer.

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 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, ce qui exclut 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 lieu 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'élément location donné.

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