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 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 ) |
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éfinissez considerIp sur false pour éviter le remplacement. |
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 de zone de localisation (LAC) pour les réseaux GSM et WCDMA. ID de réseau (NID) pour les réseaux CDMA. Indicatif 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 le code mobile : 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, l'élément 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'ID de la station de base (BID) de 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 au moins deux objets de point 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 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 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 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
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 ne montrent pas les mesures d'atténuation que vous pouvez choisir d'appliquer en tant qu'ingénieur d'application.
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
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 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 vous utilisez ce filtre, les résultats ne seront que 1c:34:56:78:9a:bc
.
restant 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 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émentlat
et un élémentlng
.accuracy
: précision de la position estimée, dans mètres. Il s'agit du rayon d'un cercle autour delocation
{ "location": { "lat": 37.421875199999995, "lng": -122.0851173 }, "accuracy": 120 }