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 l'élément Clé API. Cette clé identifie votre application à des fins de quota gestion de la sécurité. 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. Les champs suivants sont pris en charge. Tous les champs sont facultatifs, sauf mention contraire:

Champ Type JSON Description Remarques
homeMobileCountryCode number (uint32) Code MCC (Mobile country code) du réseau domestique 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 de réseau mobile du réseau domestique de l'appareil. Il s'agit du numéro MNC pour les réseaux 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. Ce champ est facultatif, mais il devrait toujours être inclus si le type de case d'option est connus du client.
Si le champ est omis, l'API Geolocation est définie par défaut sur gsm, Cela renvoie des résultats non valides ou nuls si le type de case d'option supposé est incorrecte.
carrier string Nom de l'opérateur.
considerIp boolean Indique si la géolocalisation par adresse IP doit être utilisée en cas d'absence des signaux Wi-Fi et des antennes-relais. vide ou insuffisant pour estimer la position de l'appareil. La valeur par défaut est true. Définir considerIp sur false pour empêcher le repli.
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 point d'accès Wi-Fi. ci-dessous.

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 des antennes-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 Calculer cellId ci-dessous, qui répertorie également les plages de valeurs valides pour chaque type d'option.
newRadioCellId number (uint64) Identifiant unique de la cellule NR (5G). Obligatoire pour radioType nr ; refusé pour d'autres de données.
Consultez la section Calculer newRadioCellId ci-dessous. qui indique également la plage de valeurs valide pour le champ.
locationAreaCode number (uint32) Code LAC (Location Area Code) pour les réseaux GSM et WCDMA.
ID de réseau (NID) pour les réseaux CDMA.
L'indicatif 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-65535.
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 les réseaux GSM, WCDMA, LTE et NR.
CDMA utilise l'ID système (SID).
Obligatoire.
Plage valide pour MNC: 0–999.
Plage valide pour le SID: 0-32767.

Les champs facultatifs suivants ne sont pas utilisés, mais peuvent être inclus si les 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 de 0, cellId ou newRadioCellId représente une les mesures.
signalStrength number (double) Puissance du signal radio mesurée en dBm.
timingAdvance number (double) La au plus vite .

Calcul de cellId...

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

  • Les réseaux GSM (2G) utilisent l'identifiant de cellule GSM (CID) 16 bits en l'état. Plage valide: 0-65 535.
  • Les réseaux CDMA (2G) utilisent l'identifiant BID (Base Station ID) 16 bits tel quel. Plage valide: 0-65 535.
  • Les réseaux WCDMA (3G) utilisent l'UTRAN/GERAN Cell Identity (UC-ID), qui est un nombre entier de 28 bits valeur concaténant l'identifiant RTC (Radio Network Controller Identifier) 12 bits et le code 16 bits ID de la cellule CID.
    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, résultats incorrects ou nuls.
  • Les réseaux LTE (4G) utilisent le système E-UTRAN Cell Identity (ECI), qui est un nombre entier de 28 bits en concaténant l'identifiant E-UTRAN du nœud B (eNBId) 20 bits et l'ID de cellule (CID) 8 bits.
    Formule: enb_id << 8 | cid.
    Plage valide: 0-268435455.
    Remarque:Si vous indiquez uniquement la valeur d'ID de cellule 8 bits dans les réseaux LTE, résultats 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, peut tronquer le nombre pour qu'il soit compris dans la plage documentée, déduire une correction à radioType, ou renvoyer un résultat NOT_FOUND sans aucun 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... newRadioCellId

Les réseaux récents, dont les ID de cellule sont supérieurs à 32 bits, utilisent le protocole 64 bits Champ newRadioCellId permettant de transmettre l'ID de cellule du réseau à API Geolocation.

  • Les réseaux NR (5G) utilisent la New Radio Cell Identity (NCI) 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 deux ou plus de points d'accès Wi-Fi. macAddress est obligatoire. tout les autres champs sont facultatifs.

Champ Type JSON Description Remarques
macAddress string Adresse MAC du nœud Wi-Fi. Elle est généralement appelée BSS, BSSID ou adresse MAC. Obligatoire.Chaîne hexadécimale séparée par deux points (:).
Seulement géré de manière universelle les adresses MAC peuvent être localisées via l'API. Les autres adresses MAC sont et peut entraîner l'abandon d'une requête API vide. Pour en savoir plus, consultez Supprimer l'accès à un réseau Wi-Fi inutile. points d'accès.
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 comprises entre -35 et -10 dBm. N'oubliez pas d'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ée 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 voulez essayer l'API Geolocation avec un exemple 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 la commande cURL pour Effectuez 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

Suppression des objets de point d'accès Wi-Fi dont les macAddress sont administré 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 l'échec, 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 utilisés. Cette approche est un compromis ont besoin d'une estimation de la position géographique, ainsi que de la précision et du rappel exigences. Les techniques de filtrage suivantes montrent comment filtrer les entrées, mais n'indiquez pas les mesures d'atténuation possibles, car l'application choisir d'appliquer.

Les adresses MAC administrées localement ne constituent pas des signaux de localisation utiles pour le et sont supprimés sans notification des requêtes. Vous pouvez supprimer ces adresses MAC en veillant à ce que le deuxième bit le moins significatif L'octet le plus important de macAddress est 0.Ex. : la 1 bit représenté par 2 dans 02:00:00:00:00:00 Adresse MAC de diffusion (FF:FF:FF:FF:FF:FF) est un exemple d'adresse MAC qui serait que ce filtre est utilement exclu.

Plage d'adresses MAC entre 00:00:5E:00:00:00 et 00:00:5E:FF:FF:FF sont réservé pour l'IANA et souvent utilisé pour la gestion de réseau et les fonctions de multidiffusion ce qui empêche leur utilisation comme signal de localisation. Vous devez également les supprimer les adresses MAC des entrées à 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, les résultats ne seront que 1c:34:56:78:9a:bc. restant dans la liste. Comme cette liste contient moins de deux adresses MAC Wi-Fi, le n'aurait pas abouti et une erreur HTTP 404 (notFound) de réponse est renvoyée.

Réponses de géolocalisation

Une requête de géolocalisation qui aboutit renvoie une réponse au format JSON en définissant un lieu et un rayon.

  • location: latitude et longitude estimées de l'utilisateur. en degrés. Contient un élément lat et un élément lng .
  • accuracy: précision de la position estimée, dans mètres. Il s'agit du rayon d'un cercle autour de location
{
  "location": {
    "lat": 37.421875199999995,
    "lng": -122.0851173
  },
  "accuracy": 120
}