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 ou de l'emplacement de la requête. Sauf indication contraire, les champs suivants sont acceptés et sont tous facultatifs:

Vous trouverez ci-dessous un exemple de corps de requête de 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.

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

Calcul de cellId...

Les types d'options avant 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 l'ID de cellule 16 bits en l'état. Plage valide: 0 à 65 535.
• Les réseaux CDMA (2G) utilisent l'ID de station de base (BID) 16 bits en l'état. Plage valide: 0 à 65 535.
• Les réseaux WCDMA (3G) utilisent l'UTRAN/GERAN Cell Identity (UC-ID), qui est une valeur entière de 28 bits concaténant l'identifiant RTC-ID (Radio Network Controller Identifier) 12 bits et l'ID de cellule (CID) de 16 bits.
  Formule: rnc_id << 16 | cid.
  Plage valide: 0-268435455.
  Remarque:Si vous spécifiez uniquement la valeur d'ID de cellule 16 bits dans les réseaux WCDMA, les résultats sont incorrects ou nuls.
• Les réseaux LTE (4G) utilisent le système E-UTRAN Cell Identity (ECI), qui est une valeur entière de 28 bits concaténant l'identifiant E-UTRAN Node B 20 bits (eNBId) et l'ID de cellule (CID) de 8 bits.
  Formule: enb_id << 8 | cid.
  Plage valide: 0-268435455.
  Remarque:Si vous spécifiez uniquement la valeur d'ID de cellule 8 bits dans les réseaux LTE, les résultats sont 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 seule discrétion de Google, peut tronquer le nombre pour qu'il tienne dans la plage documentée, déduire une correction de radioType ou renvoyer un résultat NOT_FOUND sans aucun indicateur dans la réponse.

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

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

Calcul de newRadioCellId...

Les réseaux récents, dont les ID de cellule sont supérieurs à 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 la nouvelle antenne radio 36 bits (NCI) telle quelle.
  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.

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

La suppression des objets de point d'accès Wi-Fi dont les macAddress sont administrés localement peut améliorer le taux de réussite des appels de l'API Geolocation qui utilisent le Wi-Fi en entrée. Si, après le filtrage, il peut être déterminé qu'un appel de l'API Geolocation échoue, des mesures d'atténuation telles que l'utilisation de signaux de localisation plus anciens ou de points d'accès Wi-Fi dont les signaux sont plus faibles peuvent être mises en œuvre. 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 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 constituent 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 important de macAddress est 0, par exemple le bit représenté par le 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:

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")));
    

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')]
    

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 ce filtre est utilisé, seul 1c:34:56:78:9a:bc reste dans la liste. Comme cette liste comporte moins de deux adresses MAC Wi-Fi, la requête n'aboutira pas 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 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
}