Requêtes et réponses concernant l'altitude

Demandes d'altitude

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

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

Ces deux approches utilisent les coordonnées de latitude/longitude pour identifier les lieux ou les sommets de chemin. 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 zones géographiques peuvent renvoyer des données moins précises, en particulier si les zones sont éloignées les unes des autres, car certaines données sont lissées.

Une requête de l'API Elevation se présente sous la forme suivante :

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

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

  • json (recommandé) : indique la sortie au format JavaScript Object Notation (JSON) ;
  • xml indique que la sortie est au format XML et encapsulée dans un nœud <ElevationResponse>.

Remarque : Pour être valides, les URL doivent être correctement encodées et ne pas dépasser 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 différentes pour les URL.

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

Paramètres de requête

Les requêtes envoyées à l'API Elevation utilisent différents paramètres selon qu'elles concernent des lieux distincts ou un chemin 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 chemins, les requêtes d'altitude sont plutôt échantillonnées le long du chemin donné.

Comme c'est la norme pour toutes les URL, les différents paramètres sont séparés par une esperluette (&amp;). La liste des paramètres et de leurs valeurs possibles est indiquée 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 emplacement sous la forme d'une paire {latitude,longitude} séparée par une virgule (par exemple, "40.714728,-73.998672") ou plusieurs paires latitude/longitude transmises sous la forme d'un tableau ou d'une polyligne encodée. Ce paramètre spécifique est limité à 512 points. Pour en savoir plus, consultez Spécifier des zones 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 chemin sur 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 chemins d'accès ci-dessous.
  • samples (obligatoire) spécifie le nombre de 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 emplacements spécifiques transmis sous forme de valeurs de latitude/longitude.

Le paramètre locations peut accepter les arguments suivants :

  • Une seule coordonnée : locations=40.714728,-73.998672
  • Tableau de coordonnées séparées par une barre verticale (|) : locations=40.714728,-73.998672|-34.397,150.644
  • 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 longitudes 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, car elle sera considérée comme incorrecte.

Vous pouvez insérer jusqu'à 512 coordonnées dans un tableau ou une polyligne encodée, tout en construisant 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 chemins d'accès

Les requêtes de tracé échantillonné sont indiquées par l'utilisation des paramètres path et samples, qui indiquent une demande de données d'altitude le long d'un tracé à des intervalles spécifiés. Comme pour les requêtes de position 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 trajet, en fonction du nombre de samples spécifié (y compris les extrémités).

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

  • Tableau de deux chaînes de texte de coordonnées ou plus, séparées par une virgule et par 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 longitudes 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, car elle sera considérée comme incorrecte.

Vous pouvez insérer jusqu'à 512 coordonnées dans un tableau ou une polyligne encodée, tout en construisant 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 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

FieldRequiredTypeDescription
required Array<ElevationResult> See ElevationResult for more information.
requiredElevationStatus See ElevationStatus for more information.
optionalstring

When the service returns a status code other than OK, there may be an additional error_message field within the response object. This field contains more detailed information about thereasons behind the given status code. This field is not always returned, and its content is subject to change.

ElevationStatus

Status codes returned by service.

  • OK indicating the API request was successful.
  • DATA_NOT_AVAILABLE indicating that there's no available data for the input locations.
  • INVALID_REQUEST indicating the API request was malformed.
  • OVER_DAILY_LIMIT indicating any of the following:
    • The API key is missing or invalid.
    • Billing has not been enabled on your account.
    • A self-imposed usage cap has been exceeded.
    • The provided method of payment is no longer valid (for example, a credit card has expired).
  • OVER_QUERY_LIMIT indicating the requestor has exceeded quota.
  • REQUEST_DENIED indicating the API did not complete the request.
  • UNKNOWN_ERROR indicating an unknown error.

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

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

ElevationResult

FieldRequiredTypeDescription
requirednumber

The elevation of the location in meters.

requiredLatLngLiteral

A location element of the position for which elevation data is being computed. Note that for path requests, the set of location elements will contain the sampled points along the path.

See LatLngLiteral for more information.

optionalnumber

The value indicating the maximum distance between data points from which the elevation was interpolated, in meters. This property will be missing if the resolution is not known. Note that elevation data becomes more coarse (larger resolution values) when multiple points are passed. To obtain the most accurate elevation value for a point, it should be queried independently.

L'objet location comporte les éléments suivants :

LatLngLiteral

An object describing a specific location with Latitude and Longitude in decimal degrees.

FieldRequiredTypeDescription
requirednumber

Latitude in decimal degrees

requirednumber

Longitude in decimal degrees

Exemples d'élévation positionnelle

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

URL

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

cURL

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

JSON

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

XML

<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, Colorado et pour la Vallée de la Mort, Californie).

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

URL

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

cURL

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 output XML :

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.

JSON

{
  "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",
}

XML

<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'une ligne droite path allant du mont Whitney, en Californie, à Badwater, en Californie, qui sont les points les plus haut et les plus bas des États-Unis continentaux. Nous demandons troissamples, ce qui inclut les deux points de terminaison et le point à mi-chemin.

URL

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

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'

JSON

{
  "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",
}

XML

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