Aperçu

Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Introduction

L'API Geolocation renvoie une position et un rayon précis à partir des données des antennes-relais et des nœuds Wi-Fi détectés par le client mobile. Ce document décrit le protocole utilisé pour envoyer ces données au serveur et renvoyer une réponse au client.

La communication est assurée via la méthode POST du protocole HTTPS. Les requêtes et les réponses sont au format JSON, et le type de contenu de ces deux éléments est application/json.

Avant de commencer

Avant de commencer à développer avec l'API Geolocation, vérifiez les exigences d'authentification (vous avez besoin d'une clé API) et les informations sur l'utilisation et la facturation de l'API (vous devez activer la facturation sur votre projet).

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, en tant que valeur d'un paramètre key. Un key correspond à 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 de l'emplacement de la requête. Sauf indication contraire, les champs suivants sont acceptés et tous les champs sont facultatifs:

Champ Type JSON Description Remarques
homeMobileCountryCode number (uint32) Code pays (CM) du réseau domicile de l'appareil. Compatible pour 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 home de l'appareil. Il s'agit du MNC pour 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. Bien que ce champ soit facultatif, il devrait toujours être inclus si le type d'option est connu du client.
Si ce champ est omis, l'API Geolocation utilise la valeur gsm par défaut, ce qui ne donne pas de résultats non valides ou zéro si le type de case à cocher est incorrect.
carrier string Nom de l'opérateur.
considerIp boolean Indique s'il faut utiliser la géolocalisation IP si les signaux Wi-Fi et émis par les antennes-relais sont manquants, vides ou insuffisants pour estimer la position de l'appareil. La valeur par défaut est true. Définissez considerIp sur false pour désactiver la fonctionnalité de 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 de point d'accès Wi-Fi ci-dessous.

Vous trouverez ci-dessous un exemple de corps de requête pour 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, un ou plusieurs objets d'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.
Reportez-vous à la section Calcul de l'ID de cellule ci-dessous, qui répertorie également les plages de valeurs valides pour chaque type de signal radio.
newRadioCellId number (uint64) Identifiant unique de la cellule NR (5G). Obligatoire pour radioType nr ; refusé pour les autres types.
Consultez la section Calcul de newRadioCellId ci-dessous, qui indique également la plage de valeurs valide pour le champ.
locationAreaCode number (uint32) Code LAC (Location Area Code) des réseaux GSM et WCDMA.
Identifiant réseau pour les réseaux CDMA.
L'indicatif de suivi (TAC) des 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: entre 0 et 65 535.
Plage valide avec nr : 0–16777215.
mobileCountryCode number (uint32) Code CM (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 du réseau mobile de l'antenne-relais. Il s'agit du MNC pour 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 actuellement, mais peuvent être inclus si des 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 mesure actuelle.
signalStrength number (double) Puissance du signal radio mesurée en dBm.
timingAdvance number (double) Valeur d'avance temporelle.

Calcul de cellId

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

  • Les réseaux GSM (2G) utilisent l'ID de cellule 16 bits (CID) tel quel. Plage valide: 0–65535.
  • Les réseaux CDMA (2G) utilisent l'ID de la station de base (16 bits) telle quelle. Plage valide: 0–65535.
  • Les réseaux WCDMA (3G) utilisent l'identité de cellule UTRAN/GERAN (UC-ID), qui est une valeur entière de 28 bits combinant l'identifiant de contrôleur de réseau radio (RNC-ID) 12 bits et l'ID de cellule (CID) 16 bits.
    Formule : rnc_id << 16 | cid.
    Plage valide: 0–268435455.
    Remarque : Si vous ne spécifiez que l'ID de cellule 16 bits des réseaux WCDMA, les résultats sont incorrects ou nuls.
  • Les réseaux LTE (4G) utilisent l'ECI (E-UTRAN Cell Identity), une valeur entière de 28 bits qui combine l'identifiant e-UTRAN du nœud B (eNBId) de 20 bits et l'ID de la cellule (CID) 8 bits.
    Formule: enb_id << 8 | cid.
    Plage valide: 0–268435455.
    Remarque : Si vous ne spécifiez que l'ID de cellule 8 bits des réseaux LTE, les résultats seront incorrects ou nuls.

Le fait de placer des valeurs en dehors de ces plages dans la requête API peut avoir un comportement indéfini. L'API peut, à la discrétion de Google, tronquer le nombre afin qu'il corresponde à la plage documentée, déduire une correction à 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.

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

Calcul de newRadioCellId

Les réseaux plus récents, dont les ID de cellule font plus de 32 bits, utilisent le champ newRadioCellId 64 bits pour transmettre l'ID de cellule du réseau à l'API Geolocation.

  • Les réseaux NR (5G) utilisent tel quel l'identité de la cellule radio 36 bits (NCI, New Radio Cell Identity) en l'état.
    Plage valide: 0–68719476735.

Vous trouverez ci-dessous un exemple d'objet d'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.

Champ Type JSON Description Remarques
macAddress string Adresse MAC du nœud Wi-Fi. Elle est généralement appelée "adresse BSS", "BSSID" ou "MAC". Obligatoire. Chaîne hexadécimale séparée par : (deux-points).
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 inférieures ou égales à -35, et comprises entre -128 et -10 dBm. Veillez à 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é en dB.

Voici un exemple d'objet point d'accès Wi-Fi.

{
  "macAddress": "9c:1c:12:b0:45:f1",
  "signalStrength": -43,
  "signalToNoiseRatio": 0,
  "channel": 11,
  "age": 0
}

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: latitude et 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. Représente le rayon d'un cercle autour du location donné.
{
  "location": {
    "lat": 37.421875199999995,
    "lng": -122.0851173
  },
  "accuracy": 120
}

Erreurs

En cas d'erreur, un corps de réponse d'erreur de format standard est renvoyé et le code d'état HTTP est défini sur un état d'erreur.

La réponse contient un objet avec un seul objet error doté des clés suivantes:

  • code: identique à l'état HTTP de la réponse.
  • message : brève description de l'erreur.
  • errors : liste des erreurs qui se sont produites. Chaque erreur contient un identifiant pour le type d'erreur (reason) et une brève description (message).

Par exemple, l'envoi d'une requête JSON non valide génèrera l'erreur suivante :

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "parseError",
    "message": "Parse Error",
   }
  ],
  "code": 400,
  "message": "Parse Error"
 }
}

Voici les erreurs possibles :

Motif Domaine HTTP Status Code Description
dailyLimitExceeded usageLimits 403 Vous avez dépassé votre limite quotidienne.
keyInvalid usageLimits 400 Votre clé API n'est pas valide pour l'API Geolocation. Veuillez vérifier que vous avez inclus la clé complète, et que vous avez acheté l'API ou activé la facturation et l'API pour obtenir le quota sans frais.
userRateLimitExceeded usageLimits 403 Vous avez dépassé la limite de requêtes que vous avez configurée dans Google Cloud Console. Cette limite est généralement définie sur le nombre de requêtes par jour, le nombre de requêtes pour 100 secondes et le nombre de requêtes pour 100 secondes par utilisateur. Cette limite doit être configurée pour éviter qu'un seul ou un petit groupe d'utilisateurs n'épuise votre quota quotidien, tout en permettant un accès raisonnable à tous les utilisateurs. Consultez la section Limiter l'utilisation des API pour configurer ces limites.
notFound geolocation 404 La requête était valide, mais n'a renvoyé aucun résultat.
parseError global 400 Le corps de la requête ne présente pas un format JSON valide. Pour en savoir plus sur chaque champ, reportez-vous à la section Corps de la requête.

Exemples de requête

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": "94:b4:0f:fd:c1:40",
      "signalStrength": -35,
      "signalToNoiseRatio": 0
    }
  ]
}

Vous pouvez ensuite utiliser cURL pour effectuer 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"

Pour les adresses Mac ci-dessus, la réponse est semblable à ce qui suit :

{
  "location": {
      "lat": 37.4241876,
      "lng": -122.0917381
  },
  "accuracy": 32.839
}

(Si vous ne disposez pas de clé API, consultez Obtenir une clé API.)

Pour effectuer des tests supplémentaires, vous pouvez collecter des informations sur votre appareil Android à l'aide du SDK Places pour Android et des API de localisation Android, et de votre appareil iOS à l'aide du SDK Places pour iOS.

Questions fréquentes

Pourquoi ma réponse de géolocalisation apparaît-elle avec un très grand rayon accuracy ?

Si votre réponse de géolocalisation affiche une valeur très élevée dans le champ accuracy, le service peut procéder à la géolocalisation en fonction de l'adresse IP de la requête, et non des points d'accès Wi-Fi ou des antennes-relais. Cela peut se produire si aucune antenne-relais ni aucun point d'accès n'est valide ni reconnu.

Pour confirmer qu'il s'agit du problème, définissez considerIp sur false dans votre requête. Si la réponse est un 404, vous avez vérifié que vos objets wifiAccessPoints et cellTowers n'étaient pas géolocalisés.