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 les données d'altitude de points géographiques sur Terre. Vous pouvez spécifier les données de localisation de deux manières:
- Sous la forme d'un ensemble d'un ou plusieurs
locations
. - Comme une série de points connectés le long d'une
path
.
Chacune de ces approches utilise des coordonnées de latitude/longitude pour identifier les points géographiques ou les sommets de tracé. Ce document décrit le format requis pour les URL de l'API Elevation et les paramètres disponibles.
L'API Elevation renvoie les données des requêtes à point unique avec la plus grande précision possible. Les requêtes par lot impliquant plusieurs emplacements peuvent renvoyer des données avec une précision moindre, en particulier si les emplacements sont séparés, car les données sont lissées.
Une requête API Elevation se présente sous la forme suivante:
https://maps.googleapis.com/maps/api/elevation/outputFormat?parameters
où outputFormat
peut être l'une des valeurs suivantes:
json
(recommandé) : indique la sortie au format JavaScript Object Notation (JSON) ; ouxml
indique la sortie au format XML, encapsulée dans un nœud<ElevationResponse>
.
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 le nombre maximal de caractères des URL peut également varier selon les navigateurs, les proxys et les serveurs.
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 chemin ordonné. Pour des lieux distincts, les requêtes d'altitude renvoient des données sur les points géographiques spécifiques transmis dans la requête. Pour un tracé, 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) la clé API de votre application. Cette clé identifie votre application à des fins de gestion des quotas. Découvrez comment obtenir une clé.
Requêtes par position
locations
(obligatoire) définit le ou les points géographiques sur Terre à partir desquels renvoyer les données d'altitude. Ce paramètre prend soit un seul point géographique en tant que 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. La limite de 512 points s'applique à ce paramètre spécifique. Pour en savoir plus, consultez la section Spécifier des emplacements ci-dessous.
Requêtes de chemin échantillonné
path
(obligatoire) définit un tracé sur 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 qui définissent un tracé le long de la surface de la Terre. Ce paramètre doit être utilisé conjointement avec le paramètresamples
décrit ci-dessous. La limite est de 512 points pour ce paramètre spécifique. Pour en savoir plus, consultez la section Spécifier des chemins d'accès ci-dessous.samples
(obligatoire) spécifie le nombre de points échantillons le long d'un tracé pour lesquels des données d'altitude doivent être renvoyées. Le paramètresamples
divise la valeurpath
donnée en un ensemble ordonné de points équidistants le long du tracé.
Spécifier des emplacements
Les requêtes de position sont indiquées à l'aide du paramètre locations
, qui indique les requêtes d'altitude pour les lieux spécifiques transmis sous forme de valeurs de latitude/longitude.
Le paramètre locations
peut utiliser 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
- 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 emplacement valide sur la face de la Terre. Les latitudes peuvent prendre n'importe quelle valeur comprise entre -90
et 90
, tandis que les valeurs de longitude peuvent être comprises 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 est considérée comme incorrecte.
Vous pouvez transmettre jusqu'à 512 coordonnées dans un tableau ou une polyligne encodée, tout en créant une URL valide.
Notez que lors de la transmission de plusieurs coordonnées, la précision des données renvoyées peut être inférieure à une résolution inférieure à celle obtenue pour une requête de données pour une seule coordonnée.
Si le nombre de points ou de coordonnées dépasse 512 points dans les paramètres "locations" ou "path", cela renvoie une réponse INVALID_REQUEST
.
Spécifier des chemins d'accès
Les requêtes de chemin échantillonné sont indiquées à l'aide des paramètres path
et samples
, indiquant une requête de données d'altitude sur 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 sur la longueur du tracé, en fonction du nombre de samples
spécifié (y compris les extrémités).
Le paramètre path
peut utiliser l'un des arguments suivants:
- Tableau de deux chaînes de texte de coordonnées séparées par une virgule ou plus, séparées 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 point géographique 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 peuvent être comprises 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 est considérée comme incorrecte.
Vous pouvez transmettre jusqu'à 512 coordonnées dans un tableau ou une polyligne encodée, tout en créant une URL valide. Notez que lors de la transmission de plusieurs coordonnées, la précision des données renvoyées peut être inférieure à une résolution inférieure à celle obtenue lors d'une demande de données pour une seule coordonnée. Si le nombre de points ou de coordonnées dépasse 512 points dans les paramètres "locations" ou "path", cela renvoie une réponse INVALID_REQUEST
.
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
Field | Required | Type | Description |
---|---|---|---|
| required | Array<ElevationResult> | See ElevationResult for more information. |
| required | ElevationStatus | See ElevationStatus for more information. |
| optional | string |
When the service returns a status code other than |
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
, l'objet de réponse Elevation peut contenir un champ error_message
supplémentaire. Ce champ contient des informations plus détaillées sur les raisons associées au code d'état donné.
La réponse contient un tableau results
avec les éléments suivants:
ElevationResult
Field | Required | Type | Description |
---|---|---|---|
| required | number | The elevation of the location in meters. |
| required | LatLngLiteral | 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. |
| optional | number | 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
contient les éléments suivants:
LatLngLiteral
An object describing a specific location with Latitude and Longitude in decimal degrees.
Field | Required | Type | Description |
---|---|---|---|
| required | number | Latitude in decimal degrees |
| required | number | Longitude in decimal degrees |
Exemples d'élévation par position
L'exemple suivant demande l'altitude de Denver (Colorado, "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 au 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 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
du mont Whitney (Californie) à Badwater (Californie), le point le plus élevé et le point le plus bas des États-Unis continentaux. Nous demandons trois samples
, ce qui inclut les deux points de terminaison et le point de 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>