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 est la clé API de votre application. Cette clé identifie 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. Sauf indication contraire, tous les champs sont facultatifs :

Voici un exemple de corps de requête de l'API Geolocation.

{
  "homeMobileCountryCode": 310,
  "homeMobileNetworkCode": 410,
  "radioType": "lte",
  "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, un ou plusieurs objets d'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 de radio antérieurs à NR (5G) utilisent le champ cellId de 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 à 65535.
• Les réseaux CDMA (2G) utilisent l'ID de station de base (BID) 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'ID de cellule (CID) de 16 bits.
  Formule : rnc_id << 16 | cid.
  Plage valide : 0 à 268435455.
  Remarque : Si vous ne spécifiez que la valeur d'ID de cellule 16 bits dans les réseaux WCDMA, vous obtiendrez des résultats incorrects ou nuls.
• Les réseaux LTE (4G) utilisent l'ECI (E-UTRAN Cell Identity), qui est une valeur entière de 28 bits concaténant l'eNBId (E-UTRAN Node B Identifier) de 20 bits et le CID (Cell ID) de 8 bits.
  Formule : enb_id << 8 | cid.
  Plage valide : 0 à 268435455.
  Remarque : Si vous ne spécifiez que la valeur d'ID de cellule 8 bits dans les réseaux LTE, vous obtiendrez des résultats incorrects ou nuls.

Si vous placez des valeurs en dehors de ces plages dans la requête API, cela peut entraîner un comportement non défini. À la discrétion de Google, l'API peut tronquer le nombre afin qu'il tienne dans la plage documentée, déduire une correction de la valeur 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, qui fait partie du corps de la requête.

{
  ...

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

La réponse à la requête précédente se présente comme suit :

{
  "location": {
    "lat": 37.7801129,
    "lng": -122.4168229
  },
  "accuracy": 180.052
}

Calcul de newRadioCellId…

Les réseaux plus 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 l'identité de cellule New Radio (NCI) de 36 bits telle quelle.
  Plage valide : 0 à 68719476735.

Vous trouverez ci-dessous un exemple d'objet d'antenne-relais NR, qui fait partie du corps de la requête.

{
  ...

  "cellTowers": [
    {
      "newRadioCellId": 68719476735,
      "mobileCountryCode": 310,
      "mobileNetworkCode": 410,
      "age": 0,
      "signalStrength": -60,
    }
  ]
}

La réponse à la requête précédente se présente comme suit :

{
  "location": {
    "lat": 37.7646157,
    "lng": -122.4127361
  },
  "accuracy": 1458.5570522410717
}

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 points d'accès fixes physiquement distincts. Le champ macAddress est obligatoire. Tous les autres sont facultatifs. Le service ignore les points d'accès qui se déplacent, comme ceux des avions et des trains.

Vous trouverez ci-dessous un exemple d'objet de point d'accès Wi-Fi, qui fait partie du corps de la requête.

{
  ...
  
  "macAddress": "f0:d5:bf:fd:12:ae",
  "signalStrength": -43,
  "signalToNoiseRatio": 0,
  "channel": 11,
  "age": 0
}

La réponse à la requête précédente se présente comme suit :

{
  "location": {
    "lat": 37.7801129,
    "lng": -122.4168229
  },
  "accuracy": 180.052
}

Exemples de requêtes

Si vous souhaitez tester 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
}

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

La suppression des objets de point d'accès Wi-Fi avec des macAddress qui sont soit une adresse de broadcast (FF:FF:FF:FF:FF:FF), soit réservés par l'IANA peut améliorer le taux de réussite des appels de l'API Geolocation qui utilisent le Wi-Fi comme entrée. Si, après le filtrage, il est déterminé qu'un appel de l'API Geolocation ne réussirait pas, des mesures d'atténuation peuvent être utilisées, comme l'utilisation de signaux de localisation plus anciens ou de points d'accès Wi-Fi avec des signaux plus faibles. Cette approche est un compromis entre le besoin d'une estimation de la 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 n'indiquent pas les mesures d'atténuation que vous pouvez choisir d'appliquer en tant qu'ingénieur d'application.

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 du réseau et les fonctions de 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 :

String[] macs = {"ff:ff:ff:ff:ff:ff", "1c:34:56:78:9a:bc", "00:00:5e:00:00:01"};
ArrayList<String> _macs = new ArrayList<>(Arrays.asList(macs));
_macs.removeIf(m -> !(!m.toUpperCase().equals("FF:FF:FF:FF:FF:FF")
                      && !m.substring(0, 8).toUpperCase().equals("00:00:5E")));
    

macs = ['ff:ff:ff:ff:ff:ff', '1c:34:56:78:9a:bc', '00:00:5e:00:00:01']
macs = [m for m in macs if (m.upper() != "FF:FF:FF:FF:FF:FF" and m[:8].upper() != '00:00:5E')]
    

macs = ['ff:ff:ff:ff:ff:ff', '1c:34:56:78:9a:bc', '00:00:5e:00:00:01'];
macs = macs.filter(m => m.toUpperCase() !== "FF:FF:FF:FF:FF:FF"
                        && 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. Comme cette liste contient moins de deux adresses MAC Wi-Fi, la requête échouerait et une réponse HTTP 404(notFound) serait 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. Il s'agit du rayon d'un cercle autour de l'élément location donné.

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

L'API renvoie une position et un rayon de précision en fonction des signaux d'entrée. Bien que l'API puisse renvoyer une position de haute précision, la précision peut varier en fonction de la source, du nombre, de la densité et de la puissance des signaux disponibles. En règle générale, vous pouvez vous attendre aux rayons de précision suivants :

• Points d'accès Wi-Fi : si la requête inclut au moins deux objets wifiAccessPoints, le rayon de précision renvoyé est généralement d'environ 20 mètres. La précision s'améliore avec le nombre de points d'accès et l'intensité des signaux (mesurée en dBm), l'intensité des signaux étant généralement comprise entre -100 et -20 dBm.
• Antennes-relais : si les informations Wi-Fi ne sont pas disponibles ou sont insuffisantes, l'API utilise cellTowers pour la localisation. La précision varie considérablement en fonction du type d'antenne-relais, de l'intensité du signal et de la densité du réseau :
  • Les macrocellules (le type le plus courant, utilisé pour la couverture de zones étendues) offrent une précision moindre. Le rayon est généralement de l'ordre de plusieurs centaines de mètres, et peut atteindre plusieurs milliers de mètres dans les zones où la couverture des antennes-relais est faible. Pour les macrocellules, il est rare d'obtenir un rayon de précision inférieur à 100 mètres. La précision est généralement plus élevée pour les antennes-relais dont le signal est fort. Les signaux forts sont généralement > -110 dBm pour LTE (plage de signal de -140 à -55 dBm), > -100 dBm pour WCDMA (plage de signal de -111 à -53 dBm), > -100 dBm pour CDMA (plage de signal de -120 à -40 dBm) et > -80 dBm pour GSM (plage de signal de -121 à -1 dBm).
  • Les petites cellules (par exemple, les femtocellules, les picocellules ou les répéteurs intérieurs) fournissent la localisation cellulaire la plus précise, avec des rayons de précision pouvant être de l'ordre de 10 à 30 mètres.
• Géolocalisation par adresse IP : si considerIp est défini sur true et qu'aucun signal Wi-Fi ou d'antenne-relais ne peut être géolocalisé, l'API estime la position en fonction de l'adresse IP de la requête. Cette méthode offre la précision la plus faible, avec des rayons pouvant atteindre des milliers de mètres. Consultez Pourquoi le rayon de précision est-il très grand ? dans le guide de dépannage.