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:

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.

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

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.

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:

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 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
}