Requêtes et réponses concernant l'altitude

Requêtes d'altitude

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

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

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

L'API Elevation renvoie des données pour des requêtes à un seul point de la plus grande précision possible. Requêtes par lot impliquant plusieurs emplacements peut renvoyer des données moins précises, en particulier si les zones géographiques sont dispersées. car un lissage des données se produit.

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

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

outputFormat peut correspondre à l'une des valeurs suivantes:

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

Remarque: Les URL doivent être au format correctement encodé sont valides et sont limités à 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, Les proxys et les serveurs peuvent également avoir des limites du nombre de caractères 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 que la demande concerne des emplacements distincts ou un chemin d'accès ordonné. Pour les points géographiques distincts, les requêtes de retour de l'altitude des données sur les établissements spécifiques transmis dans la demande ; pour les chemins d'accès, les demandes d'altitude sont échantillonnées le long du tracé donné.

Comme pour toutes les URL, les paramètres sont séparés à l'aide de l'esperluette (&amp;). La liste des paramètres et leurs valeurs possibles sont indiquées ci-dessous.

Toutes les demandes

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

Demandes de position

  • locations (obligatoire) définit le ou les lieux sur la Terre à partir de laquelle renvoyer les données d'altitude. Ce paramètre prend soit un point géographique unique 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 transmis sous forme de tableau ou de polyligne encodée. La limite est de 512 points. pour ce paramètre spécifique. Pour plus d'informations, consultez la section Spécifier des zones géographiques ci-dessous.

Requêtes de chemin échantillonné

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

Spécifier des emplacements

Les demandes de position sont indiquées à l'aide de la classe Paramètre locations, indiquant les demandes d'altitude pour les établissements spécifiques transmis en tant que de latitude et de longitude.

Le paramètre locations peut prendre les valeurs suivantes : arguments:

  • Une seule coordonnée: locations=40.714728,-73.998672
  • Tableau de coordonnées séparées par une barre verticale ("|") caractère: locations=40.714728,-73.998672|-34.397,150.644
  • Un ensemble de coordonnées encodées à l'aide de la méthode Encodée Algorithme de la polyligne: locations=enc:gfo}EtohhU

Les chaînes de coordonnées de latitude et de longitude sont définies à l'aide de chiffres. au sein d'une chaîne de texte séparée par des virgules. Exemple : "40.714728,-73.998672" est une valeur locations valide. Latitude et les valeurs de longitude doivent correspondre à un lieu valide sur la surface de la Terre. Les latitudes peuvent prendre n'importe quelle valeur comprise entre -90 et 90, tandis que les valeurs de longitude toute valeur comprise entre -180 et 180. Si vous indiquez une valeur de latitude ou de longitude non valide, votre demande sera refusée comme une requête incorrecte.

Vous pouvez transmettre jusqu'à 512 coordonnées dans un tableau ou encodées. tout en créant une URL valide. Notez que lorsque vous transmettez plusieurs coordonnées, la précision des données renvoyées peut avoir une résolution inférieure à celle des données demandées pour une seule coordonnée. Les "lieux" contiennent plus de 512 points ou coordonnées. ou "path" renvoie un Réponse INVALID_REQUEST.

Spécifier des chemins d'accès

Les requêtes de chemin échantillonné sont indiquées à l'aide de path. et samples, ce qui indique une requête de données d'altitude. le long d'un tracé à des intervalles donnés. Comme pour les requêtes de position utilisant locations, le paramètre path spécifie un ensemble de valeurs de latitude et de longitude. Cependant, contrairement à une demande de position, path spécifie un ensemble ordonné de sommets. Plutôt que de revenir données d'altitude uniquement au niveau des sommets, les requêtes de tracé sont échantillonnées le long longueur du chemin, en fonction du nombre de samples spécifiés (points de terminaison inclus).

Le paramètre path peut avoir l'une des valeurs suivantes : arguments:

  • Tableau de deux ou plusieurs chaînes de texte de coordonnées séparées par une virgule séparés à l'aide de la barre verticale ("|") caractère: path=40.714728,-73.998672|-34.397,150.644
  • Coordonnées encodées à l'aide de la méthode Encodée Algorithme de la polyligne: path=enc:gfo}EtohhUxD@bAxJmGF

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

Vous pouvez transmettre jusqu'à 512 coordonnées dans un tableau ou encodées. tout en créant une URL valide. Notez que lorsque vous transmettez plusieurs la précision des données renvoyées peut être d'une résolution inférieure lorsque vous demandez des données pour une seule coordonnée. Au-delà de 512 points ou coordonnées dans "locations" ou "path" renvoie une réponse INVALID_REQUEST.

Réponses d'altitude

Pour chaque requête valide, le service Elevation renvoie une valeur 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 n'est pas OK, il peut y avoir error_message dans l'objet de réponse "Elevation". Ce champ contient plus des informations détaillées sur les raisons de ce code d'état.

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'altitude positionnelle

L'exemple suivant demande l'altitude pour Denver, 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 illustre des réponses multiples (pour Denver, Colorado et pour la vallée de la Mort, en Californie).

Cette requête illustre l'utilisation de 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 illustre l'utilisation de l'indicateur 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 voir des 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 entre le mont Whitney et Badwater, en Californie, le point le plus élevé les points les plus bas des États-Unis continentaux. Nous vous demandons samples, qui inclut les deux points de terminaison et les à 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>