Google Maps Geolocation API

Présentation

Google Maps Geolocation API renvoie un point géographique 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 retourner une réponse au client.

La communication est assurée via la méthode POST du protocole HTTPS. La requête et la réponse sont toutes les deux configurées au format JSON et leur contenu est de type application/json.

Avant de commencer à développer avec Geolocation API, consultez les exigences d'authentification (vous avez besoin d'une clé d'API) et les limites d'utilisation de l'API.

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, sous la forme d'une valeur de paramètre de clé. Une clé correspond à la clé d'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. Les champs suivants sont pris en charge et tous les champs sont facultatifs :

• homeMobileCountryCode : Code MCC (Mobile Country Code) du réseau local de l'appareil.
• homeMobileNetworkCode : Code MNC (Mobile Network Code) du réseau local de l'appareil.
• radioType : Type du réseau de téléphonie mobile. Les valeurs prises en charge sont lte, gsm, cdma et wcdma. Même si ce champ est facultatif, pour obtenir des résultats plus précis, il doit être inclus si une valeur est disponible.
• carrier : Nom de l'opérateur.
• considerIp : Spécifie le basculement vers la géolocalisation IP en cas d'indisponibilité des signaux Wi-Fi et des antennes-relais. Notez que l'adresse IP dans l'en-tête de la requête ne peut pas être l'adresse IP de l'appareil. Sa valeur par défaut est true. Définissez considerIp sur la valeur false pour désactiver le basculement.
• cellTowers : Tableau d'objets antenne-relais. Voir Objets antenne-relais ci-dessous.
• wifiAccessPoints : Tableau d'objets point d'accès Wi-Fi. Voir Objets point d'accès Wi-Fi ci-dessous.

{
  "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 peut contenir plusieurs objets antenne-relais ou aucun.

• cellId (obligatoire) : Identifiant cellulaire unique. Sur GSM, il s'agit du code CID (Cell ID) ; les réseaux CDMA utilisent le code BID (Base Station ID). Les réseaux WCDMA utilisent le code UC-Id (UTRAN/GERAN Cell Identity), une valeur 32 bits qui regroupe le contrôleur RNC (Radio Network Controller) et le code Cell ID. Sur les réseaux WCDMA, si vous spécifiez uniquement la valeur Cell ID de 16 bits, les résultats risquent d'être inexacts.
• locationAreaCode (obligatoire) : Code LAC (Location Area Code) des réseaux GSM et WCDMA. Code NID (Network ID) des réseaux CDMA.
• mobileCountryCode (obligatoire) : Code MCC (Mobile Country Code) de l'antenne-relais.
• mobileNetworkCode (obligatoire) : Code MNC (Mobile Network Code) de l'antenne-relais. Il s'agit du code MNC des réseaux GSM et WCDMA ; les réseaux CDMA utilisent le code SID (System ID).

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

• age : Temps écoulé en millisecondes depuis que cette cellule est la cellule principale. Si le champ age a la valeur 0, le champ cellId représente une mesure actuelle.
• signalStrength : Puissance du signal radio mesurée en dBm.
• timingAdvance : Valeur d'avance temporelle.

Voici un exemple d'objet antenne-relais GSM.

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

Voici un exemple objet d'antenne-relais WCDMA.

{
  "cellTowers": [
    {
      "cellId": 21532831,
      "locationAreaCode": 2862,
      "mobileCountryCode": 214,
      "mobileNetworkCode": 7
    }
  ]
}

Objets point d'accès Wi-Fi

Le tableau wifiAccessPoints dans le corps de la requête contient au moins deux objets point d'accès Wi-Fi. Le champ macAddress est obligatoire ; tous les autres champs sont facultatifs.

• macAddress : (obligatoire) Adresse MAC du nœud Wi-Fi. Les séparateurs doivent être : (deux-points).
• signalStrength : Puissance actuelle du signal, mesurée en dBm.
• age : Temps écoulé en millisecondes depuis que ce point d'accès a été détecté.
• channel : Canal sur lequel le client communique avec le point d'accès.
• signalToNoiseRatio : Rapport signal-bruit actuel mesuré en dB.

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

{
  "macAddress": "00:25:9c:cf:1c:ac",
  "signalStrength": -43,
  "age": 0,
  "channel": 11,
  "signalToNoiseRatio": 0
}

Réponses de géolocalisation

Une requête de géolocalisation valide renvoie une réponse au format JSON spécifiant un point géographique et un rayon.

• location : Latitude et longitude estimées de l'utilisateur, en degrés. Contient les champs secondaires lat et lng.
• accuracy : Précision du point géographique estimé, en mètres. Représente le rayon d'un cercle autour du point géographique (location) donné.

{
  "location": {
    "lat": 51.0,
    "lng": -0.1
  },
  "accuracy": 1200.4
}

Erreurs

En cas d'erreur, une réponse d'erreur au format standard sera renvoyée et le code de statut HTTP prendra la valeur d'un statut d'erreur.

La réponse contient un objet avec un seul objet erreur (error) et les clés suivantes :

• code : Correspond au statut HTTP de la réponse.
• message : Description courte de l'erreur.
• errors : Liste des erreurs rencontrées. Chaque erreur contient un identifiant pour le type d'erreur (paramètre reason) et une courte description (paramètre 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	Code de statut HTTP	Description
dailyLimitExceeded	usageLimits	403	Vous avez dépassé votre limite journalière.
keyInvalid	usageLimits	400	Votre clé d'API n'est pas valide pour Google Maps Geolocation API. Vérifiez que vous avez inclus la clé complète et que vous avez acheté l'API ou activé la facturation et l'API pour bénéficier du quota gratuit.
userRateLimitExceeded	usageLimits	403	Vous avez dépassé le nombre limite de requêtes par seconde et par utilisateur que vous avez configuré dans la Google API Console. Cette limite doit être configurée afin d'empêcher un utilisateur ou un petit groupe d'utilisateurs d'épuiser votre quota journalier, tout en accordant un accès raisonnable à tous les utilisateurs.
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 plus de détails sur chaque champ, reportez-vous à la section Corps de la requête.

Exemples de requête

Remarque : Il arrive que les adresses Mac changent. C'est pourquoi les exemples de cette page peuvent renvoyer un message d'erreur de l'API.

Pour tester Google Maps Geolocation API avec des exemples de données, enregistrez la requête JSON suivante dans un fichier :

{
  "considerIp": "false",
  "wifiAccessPoints": [
    {
        "macAddress": "00:25:9c:cf:1c:ac",
        "signalStrength": -43,
        "signalToNoiseRatio": 0
    },
    {
        "macAddress": "00:25:9c:cf:1c:ad",
        "signalStrength": -55,
        "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": 33.3632256,
    "lng": -117.0874871
  },
  "accuracy": 20
}

(Si vous n'avez pas de clé d'API, voir Obtenir une clé.)

Pour effectuer des tests supplémentaires, vous pouvez récupérer des informations depuis votre appareil Android à l'aide de Google Places API for Android et des API de géolocalisation pour Android, et depuis votre appareil iOS à l'aide de Google Places API for iOS.

FAQ

Pourquoi la réponse de géolocalisation indique-t-elle un rayon de précision (accuracy) très large ?

Si votre réponse de géolocalisation affiche une valeur très élevée dans le champ accuracy, le service effectue peut-être la géolocalisation à partir de l'IP de la requête et non des points Wi-Fi ou des antennes-relais. Ce problème peut survenir lorsqu'aucune antenne-relais ni aucun point d'accès n'est valide ou détecté(e).

Pour vérifier qu'il s'agit bien de cette erreur, attribuez au champ considerIp la valeur false dans votre requête. La réponse 404 vient confirmer que vos objets wifiAccessPoints et cellTowers n'ont pas pu être géolocalisés.