Requêtes et réponses concernant l'altitude

Requêtes d'altitude

Les requêtes de l'API Elevation sont construites sous forme de chaîne URL. L'API renvoie des données d'altitude pour des lieux sur Terre. Vous pouvez spécifier les données de localisation de deux manières :

• Sous forme d'ensemble d'un ou de plusieurs locations.
• Sous forme de série de points connectés le long d'un path.

Ces deux approches utilisent des coordonnées de latitude/longitude pour identifier les lieux ou les sommets du tracé. Ce document décrit le format requis des URL de l'API Elevation et les paramètres disponibles.

L'API Elevation renvoie des données pour les requêtes à point unique avec la plus grande précision possible. Les requêtes par lot impliquant plusieurs lieux peuvent renvoyer des données moins précises, en particulier si les lieux sont éloignés les uns des autres, car un lissage des données se produit.

Une requête de l'API Elevation se présente comme suit :

https://maps.googleapis.com/maps/api/elevation/outputFormat?parameters

où outputFormat peut prendre l'une des valeurs suivantes :

• json (recommandé) indique une sortie au format JSON (JavaScript Object Notation) ; ou
• xml, indique une sortie au format XML, encapsulée dans un <ElevationResponse> nœud.

Remarque : Les URL doivent être correctement encodées pour être valides et sont limitées à 16 384 caractères pour tous les services Web. Tenez compte de cette limite lorsque vous créez vos URL. Notez que différents navigateurs, proxys et serveurs peuvent également avoir des limites de caractères d'URL différentes.

HTTPS est requis pour les requêtes qui utilisent une clé API.

Paramètres de requête

Les requêtes adressées à l'API Elevation utilisent différents paramètres selon qu'elles concernent des lieux distincts ou un tracé ordonné. Pour les lieux distincts, les requêtes d'altitude renvoient des données sur les lieux spécifiques transmis dans la requête. Pour les tracés, les requêtes d'altitude sont plutôt échantillonnées le long du tracé donné.

Comme c'est la norme pour toutes les URL, les paramètres sont séparés par une esperluette (&). La liste des paramètres et leurs valeurs possibles sont indiquées ci-dessous.

Toutes les demandes

• key : (obligatoire) clé API de votre application. Cette clé identifie votre application à des fins de gestion des quotas. Découvrez comment obtenir une clé.

Requêtes positionnelles

• locations : (obligatoire) définit le ou les lieux sur Terre pour lesquels les données d'altitude doivent être renvoyées. Ce paramètre accepte un seul lieu sous forme de paire {latitude,longitude} séparée par une virgule (par exemple, "40.714728,-73.998672") ou plusieurs paires latitude/longitude transmises sous forme de tableau ou de polyligne encodée. Ce paramètre spécifique est limité à 512 points. Pour en savoir plus, consultez la section Spécifier des lieux ci-dessous.

Requêtes de tracé échantillonné

• path : (obligatoire) définit un tracé sur la Terre pour lequel renvoyer des données d'altitude. Ce paramètre définit un ensemble d'au moins deux paires {latitude,longitude} ordonnées définissant un tracé le long de la surface de la Terre. Ce paramètre doit être utilisé conjointement avec le paramètre samples décrit ci-dessous. Ce paramètre spécifique est limité à 512 points. Pour en savoir plus, consultez la section Spécifier des tracés ci-dessous.
• samples : (obligatoire) spécifie le nombre points échantillonnés le long d'un chemin pour lesquels renvoyer des données d'altitude. Le paramètre samples divise le path donné en un ensemble ordonné de points équidistants le long du chemin.

Spécifier des emplacements

Les requêtes positionnelles sont indiquées par l'utilisation du paramètre locations, qui indique les requêtes d'altitude pour les lieux spécifiques transmis en tant que valeurs de latitude/longitude.

Le paramètre locations peut accepter les arguments suivants :

• Une seule coordonnée : locations=40.714728,-73.998672
• Un tableau de coordonnées séparées par une barre verticale ("|") : locations=40.714728,-73.998672|-34.397,150.644
• Un ensemble de coordonnées encodées à l'aide de l'algorithme de polyligne encodée: locations=enc:gfo}EtohhU

Les chaînes de coordonnées de latitude et de longitude sont définies à l'aide de chiffres dans une chaîne de texte séparée par des virgules. Par exemple, "40.714728,-73.998672" est une valeur locations valide. Les valeurs de latitude et de longitude doivent correspondre à un lieu valide sur la surface de la Terre. Les latitudes peuvent prendre n'importe quelle valeur entre -90 et 90, tandis que les valeurs de longitude peuvent prendre n'importe quelle valeur entre -180 et 180. Si vous spécifiez une valeur de latitude ou de longitude non valide, votre requête sera rejetée en tant que requête incorrecte.

Vous pouvez transmettre jusqu'à 512 coordonnées dans un tableau ou une polyligne encodée, tout en créant une URL valide. Notez toutefois qu'en transmettant plusieurs coordonnées à la fois, l'exactitude des données renvoyées peut être moindre que lorsque votre requête ne porte que sur une seule coordonnée. Si vous dépassez 512 points ou coordonnées dans les paramètres "locations" ou "path", une réponse INVALID_REQUEST est renvoyée.

Spécifier des tracés

Les requêtes de tracé échantillonné sont indiquées par l'utilisation des paramètres path et samples, qui indiquent une requête de données d'altitude le long d'un tracé à des intervalles spécifiés. Comme pour les requêtes positionnelles utilisant le paramètre locations, le paramètre path spécifie un ensemble de valeurs de latitude et de longitude. Toutefois, contrairement à une requête de position, path spécifie un ensemble ordonné de sommets. Plutôt que de renvoyer des données d'altitude uniquement aux sommets, les requêtes de tracé sont échantillonnées le long du tracé, en fonction du nombre de samples spécifiés (y compris les extrémités).

Le paramètre path peut accepter l'un des arguments suivants :

• Un tableau d'au moins deux chaînes de texte de coordonnées séparées par une virgule et une barre verticale ('|') : path=40.714728,-73.998672|-34.397,150.644
• Coordonnées encodées à l'aide de l'algorithme de polyligne encodée : path=enc:gfo}EtohhUxD@bAxJmGF

Les chaînes de coordonnées de latitude et de longitude sont définies à l'aide de chiffres dans une chaîne de texte séparée par des virgules. Par exemple, "40.714728,-73.998672|-34.397, 150.644" est une valeur path valide. Les valeurs de latitude et de longitude doivent correspondre à un lieu valide sur la surface de la Terre. Les latitudes peuvent prendre n'importe quelle valeur entre -90 et 90, tandis que les valeurs de longitude peuvent prendre n'importe quelle valeur entre -180 et 180. Si vous spécifiez une valeur de latitude ou de longitude non valide, votre requête sera rejetée en tant que requête incorrecte.

Vous pouvez transmettre jusqu'à 512 coordonnées dans un tableau ou une polyligne encodée, tout en créant une URL valide. Notez toutefois qu'en transmettant plusieurs coordonnées à la fois, l'exactitude des données renvoyées peut être moindre que lorsque votre requête ne porte que sur une seule coordonnée. Si vous dépassez 512 points ou coordonnées dans les paramètres "locations" ou "path", une réponse INVALID_REQUEST est renvoyée.

Réponses aux requêtes d'altitude

• Un tableau d'au moins deux chaînes de texte de coordonnées séparées par une virgule et une barre verticale ('|') : path=40.714728,-73.998672|-34.397,150.644
• Coordonnées encodées à l'aide de l'algorithme de polyligne encodée : path=enc:gfo}EtohhUxD@bAxJmGF

Les chaînes de coordonnées de latitude et de longitude sont définies à l'aide de chiffres dans une chaîne de texte séparée par des virgules. Par exemple, "40.714728,-73.998672|-34.397, 150.644" est une valeur path valide. Les valeurs de latitude et de longitude doivent correspondre à un lieu valide sur la surface de la Terre. Les latitudes peuvent prendre n'importe quelle valeur entre -90 et 90, tandis que les valeurs de longitude peuvent prendre n'importe quelle valeur entre -180 et -180. Si vous spécifiez une valeur de latitude ou de longitude non valide, votre requête sera rejetée en tant que requête incorrecte.

Vous pouvez transmettre jusqu'à 512 coordonnées dans un tableau ou une polyligne encodée, tout en créant une URL valide. Notez toutefois qu'en transmettant plusieurs coordonnées à la fois, l'exactitude des données renvoyées peut être moindre que lorsque votre requête ne porte que sur une seule coordonnée. Si vous dépassez 512 points ou coordonnées dans les paramètres "locations" ou "path", une réponse INVALID_REQUEST est renvoyée.

Réponses aux requêtes d'altitude

Pour chaque requête valide, le service Elevation renvoie une réponse Elevation au format indiqué dans l'URL de la requête.

ElevationResponse

ElevationStatus

Codes d'état renvoyés par le service.

• OK indique que la requête API a abouti.
• DATA_NOT_AVAILABLE indique qu'aucune donnée n'est disponible pour les lieux d'entrée.
• INVALID_REQUEST indique que la requête API n'a pas été rédigée correctement.
• OVER_DAILY_LIMIT indique l'un des éléments suivants :
  • La clé API est manquante ou non valide.
  • La facturation n'a pas été activée sur votre compte.
  • La limite d'utilisation que vous avez définie vous-même a été dépassée.
  • Le mode de facturation fourni n'est plus valide (une carte de crédit est arrivée à expiration, par exemple).
• OVER_QUERY_LIMIT indique que le demandeur a dépassé le quota.
• REQUEST_DENIED indique que l'API n'a pas terminé la requête.
• UNKNOWN_ERROR indique une erreur inconnue.

Lorsque le code d'état est différent de OK, un champ error_message supplémentaire peut être présent dans l'objet de réponse Elevation. Ce champ contient des informations plus détaillées sur les raisons du code d'état donné.

La réponse contient un tableau results avec les éléments suivants :

ElevationResult

LatLngLiteral

Objet décrivant un lieu spécifique avec la latitude et la longitude en degrés décimaux.

Exemples d'altitude positionnelle

L'exemple suivant demande l'altitude de Denver, dans le Colorado, la "Mile High City" :

https://maps.googleapis.com/maps/api/elevation/json
    ?locations=39.7391536%2C-104.9847034
    &key=YOUR_API_KEY
      

curl -L -X GET 'https://maps.googleapis.com/maps/api/elevation/json?locations=39.7391536%2C-104.9847034&key=YOUR_API_KEY'
      

        
{
  "results":
    [
      {
        "elevation": 1608.637939453125,
        "location": { "lat": 39.7391536, "lng": -104.9847034 },
        "resolution": 4.771975994110107,
      },
    ],
  "status": "OK",
}
        
        

        
<ElevationResponse>
 <status>OK</status>
 <result>
  <location>
   <lat>39.7391536</lat>
   <lng>-104.9847034</lng>
  </location>
  <elevation>1608.6379395</elevation>
  <resolution>4.7719760</resolution>
 </result>
</ElevationResponse>
        
        

L'exemple suivant montre plusieurs réponses (pour Denver, dans le Colorado, et pour la Vallée de la Mort, en Californie).

Cette requête montre comment utiliser l'option JSON output :

https://maps.googleapis.com/maps/api/elevation/json
    ?locations=39.7391536%2C-104.9847034%7C36.455556%2C-116.866667
    &key=YOUR_API_KEY
      

curl -L -X GET 'https://maps.googleapis.com/maps/api/elevation/json?locations=39.7391536%2C-104.9847034%7C36.455556%2C-116.866667&key=YOUR_API_KEY'
      

Cette requête montre comment utiliser l'option XML output :

https://maps.googleapis.com/maps/api/elevation/xml?locations=39.7391536,-104.9847034|36.455556,-116.866667&key=YOUR_API_KEY

Sélectionnez les onglets ci-dessous pour afficher les exemples de réponses JSON et XML.

      
{
  "results":
    [
      {
        "elevation": 1608.637939453125,
        "location": { "lat": 39.7391536, "lng": -104.9847034 },
        "resolution": 4.771975994110107,
      },
      {
        "elevation": -52.79492568969727,
        "location": { "lat": 36.455556, "lng": -116.866667 },
        "resolution": 19.08790397644043,
      },
    ],
  "status": "OK",
}
      
      

      
<ElevationResponse>
 <status>OK</status>
 <result>
  <location>
   <lat>39.7391536</lat>
   <lng>-104.9847034</lng>
  </location>
  <elevation>1608.6379395</elevation>
  <resolution>4.7719760</resolution>
 </result>
 <result>
  <location>
   <lat>36.4555560</lat>
   <lng>-116.8666670</lng>
  </location>
  <elevation>-52.7949257</elevation>
  <resolution>19.0879040</resolution>
 </result>
</ElevationResponse>
      
      

Les exemples suivants demandent des données d'altitude le long d'un path en ligne droite entre le mont Whitney, en Californie, et Badwater, en Californie, les points les plus hauts et les plus bas des États-Unis continentaux. Nous demandons trois samples, qui incluront donc les deux points de terminaison et le point médian.

https://maps.googleapis.com/maps/api/elevation/json
  ?path=36.578581%2C-118.291994%7C36.23998%2C-116.83171
  &samples=3
  &key=YOUR_API_KEY
    

curl -L -X GET 'https://maps.googleapis.com/maps/api/elevation/json?path=36.578581%2C-118.291994%7C36.23998%2C-116.83171&samples=3&key=YOUR_API_KEY'
    

      
{
  "results":
    [
      {
        "elevation": 4411.94189453125,
        "location": { "lat": 36.578581, "lng": -118.291994 },
        "resolution": 19.08790397644043,
      },
      {
        "elevation": 1372.8359375,
        "location": { "lat": 36.41150289067028, "lng": -117.5602607523847 },
        "resolution": 9.543951988220215,
      },
      {
        "elevation": -84.51690673828125,
        "location": { "lat": 36.23998, "lng": -116.83171 },
        "resolution": 9.543951988220215,
      },
    ],
  "status": "OK",
}
      
      

      
<ElevationResponse>
 <status>OK</status>
 <result>
  <location>
   <lat>36.5785810</lat>
   <lng>-118.2919940</lng>
  </location>
  <elevation>4411.9418945</elevation>
  <resolution>19.0879040</resolution>
 </result>
 <result>
  <location>
   <lat>36.4115029</lat>
   <lng>-117.5602608</lng>
  </location>
  <elevation>1372.8359375</elevation>
  <resolution>9.5439520</resolution>
 </result>
 <result>
  <location>
   <lat>36.2399800</lat>
   <lng>-116.8317100</lng>
  </location>
  <elevation>-84.5169067</elevation>
  <resolution>9.5439520</resolution>
 </result>
</ElevationResponse>