Solicitudes de elevación y respuestas

Solicitudes de Elevation

Las solicitudes a la API de Elevation se crean como una cadena de URL. La API devuelve datos de elevación para ubicaciones de la Tierra. Puedes especificar los datos de ubicación de una de estas dos maneras:

  • Como un conjunto de uno o más locations.
  • Como una serie de puntos conectados a lo largo de un path

En ambos enfoques, se usan coordenadas de latitud y longitud para identificar las ubicaciones o los vértices de la ruta. En este documento, se describe el formato obligatorio de las URLs de la API de Elevation y los parámetros disponibles.

La API de Elevation devuelve datos para consultas de un solo punto con la mayor precisión posible. Las consultas por lotes que involucran varias ubicaciones pueden devolver datos con menos precisión, en especial si las ubicaciones están separadas, ya que se produce cierta suavización de los datos.

Una solicitud a la API de Elevation tiene el siguiente formato:

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

En el ejemplo anterior, outputFormat puede ser cualquiera de los siguientes valores:

  • json (recomendado), indica el resultado en notación de objetos de JavaScript (JSON)
  • xml: Indica que el resultado se muestra en formato XML, dentro de un nodo <ElevationResponse>.

Nota: Las URLs deben estar codificadas correctamente para ser válidas y tienen un límite de 16,384 caracteres en todos los servicios web. Ten en cuenta este límite cuando construyas tus URLs. Ten en cuenta que los diferentes navegadores, proxies y servidores también pueden tener diferentes límites de caracteres de URL.

Se requiere HTTPS para las solicitudes que usan una clave de API.

Parámetros de solicitud

Las solicitudes a la API de Elevation utilizan diferentes parámetros según si la solicitud es para ubicaciones discretas o para una ruta ordenada. En el caso de las ubicaciones discretas, las solicitudes de elevación devuelven datos sobre las ubicaciones específicas que se pasan en la solicitud. En el caso de las rutas, las solicitudes de elevación se muestrean a lo largo de la ruta determinada.

Tal como es práctica estándar para todas las URLs, los parámetros se separan usando el signo et (&amp;). A continuación, se indican la lista de parámetros y sus valores posibles.

Todas las solicitudes

  • key: (obligatorio) Es la clave de API de tu aplicación. Esta clave identifica tu aplicación para administrar las cuotas. Obtén información para obtener una clave.

Solicitudes de posición

  • locations (obligatorio) define las ubicaciones de la Tierra a partir de las cuales se muestran los datos de elevación. Este parámetro toma una sola ubicación como un par {latitud,longitud} separado por comas (p.ej., "40.714728,-73.998672") o varios pares de latitud y longitud pasados como un array o como una polilínea codificada. Hay un límite de 512 puntos para este parámetro específico. Para obtener más información, consulta Especifica ubicaciones más abajo.

Solicitudes de rutas con muestras

  • path (obligatorio): Define una ruta en la Tierra para la cual se deben mostrar datos de elevación. Este parámetro define un conjunto de dos o más pares de coordenadas (latitud y longitud) que definen una ruta a lo largo de la superficie de la Tierra. Este parámetro se debe usar junto con el parámetro samples que se describe a continuación. Hay un límite de 512 puntos para este parámetro específico. Para obtener más información, consulta Especifica rutas de acceso más abajo.
  • samples (obligatorio): Especifica la cantidad de puntos de muestra a lo largo de una ruta para la que se muestran datos de elevación. El parámetro samples divide el objeto path determinado en un conjunto ordenado de puntos equidistantes a lo largo de la ruta.

Especifica ubicaciones

Las solicitudes posicionales se indican con el parámetro locations, que indica las solicitudes de elevación para las ubicaciones específicas que se pasan como valores de latitud y longitud.

El parámetro locations puede tomar los siguientes argumentos:

  • Una sola coordenada: locations=40.714728,-73.998672
  • Un array de coordenadas separadas con el carácter de barra vertical ('|'): locations=40.714728,-73.998672|-34.397,150.644
  • Es un conjunto de coordenadas codificadas con el algoritmo de polilínea codificada: locations=enc:gfo}EtohhU

Las cadenas de coordenadas de latitud y longitud se definen con números dentro de una cadena de texto separada por comas. Por ejemplo, "40.714728,-73.998672" es un valor de locations válido. Los valores de latitud y longitud deben corresponder a una ubicación válida en la superficie de la Tierra. Las latitudes pueden tomar cualquier valor entre -90 y 90, mientras que los valores de longitud pueden tomar cualquier valor entre -180 y 180. Si especificas un valor de latitud o longitud no válido, se rechazará tu solicitud como incorrecta.

Puedes pasar hasta 512 coordenadas en un array o una polilínea codificada, y, al mismo tiempo, construir una URL válida. Ten en cuenta que, cuando se pasan varias coordenadas, la precisión de los datos resultantes puede ser inferior que cuando se solicitan datos para una única coordenada. Si se superan los 512 puntos o coordenadas en los parámetros "locations" o "path", se devuelve una respuesta INVALID_REQUEST.

Especifica rutas

Las solicitudes de ruta de acceso muestreadas se indican mediante el uso de los parámetros path y samples, que indican una solicitud de datos de elevación a lo largo de una ruta de acceso en intervalos especificados. Al igual que con las solicitudes posicionales que usan el parámetro locations, el parámetro path especifica un conjunto de valores de latitud y longitud. Sin embargo, a diferencia de una solicitud posicional, la path especifica un conjunto ordenado de vértices. En lugar de mostrar los datos de elevación solo en los vértices, las solicitudes de ruta se muestrean a lo largo de la ruta, según la cantidad de samples especificados (incluidos los extremos).

El parámetro path puede tomar cualquiera de los siguientes argumentos:

  • Un array de dos o más cadenas de texto de coordenadas separadas por comas y por el carácter de barra vertical ('|'): path=40.714728,-73.998672|-34.397,150.644
  • Coordenadas codificadas con el algoritmo de polilínea codificada: path=enc:gfo}EtohhUxD@bAxJmGF

Las cadenas de coordenadas de latitud y longitud se definen con números dentro de una cadena de texto separada por comas. Por ejemplo, "40.714728,-73.998672|-34.397, 150.644" es un valor de path válido. Los valores de latitud y longitud deben corresponder a una ubicación válida en la superficie de la Tierra. Las latitudes pueden tomar cualquier valor entre -90 y 90, mientras que los valores de longitud pueden tomar cualquier valor entre -180 y 180. Si especificas un valor de latitud o longitud no válido, tu solicitud se rechazará como incorrecta.

Puedes pasar hasta 512 coordenadas en un array o una polilínea codificada, y, al mismo tiempo, construir una URL válida. Ten en cuenta que, cuando se pasan varias coordenadas, la precisión de los datos resultantes puede ser inferior que cuando se solicitan datos para una única coordenada. Si se superan los 512 puntos o coordenadas en los parámetros "locations" o "path", se devuelve una respuesta INVALID_REQUEST.

Respuestas de Elevation

  • Un array de dos o más cadenas de texto de coordenadas separadas por comas y por el carácter de barra vertical ('|'): path=40.714728,-73.998672|-34.397,150.644
  • Coordenadas codificadas con el algoritmo de polilínea codificada: path=enc:gfo}EtohhUxD@bAxJmGF

Las cadenas de coordenadas de latitud y longitud se definen con números dentro de una cadena de texto separada por comas. Por ejemplo, "40.714728,-73.998672|-34.397, 150.644" es un valor de path válido. Los valores de latitud y longitud deben corresponder a una ubicación válida en la superficie de la Tierra. Las latitudes pueden tomar cualquier valor entre -90 y 90, mientras que los valores de longitud pueden tomar cualquier valor entre -180 y -180. Si especificas un valor de latitud o longitud no válido, tu solicitud se rechazará como incorrecta.

Puedes pasar hasta 512 coordenadas en un array o una polilínea codificada, y, al mismo tiempo, construir una URL válida. Ten en cuenta que, cuando se pasan varias coordenadas, la precisión de los datos resultantes puede ser inferior que cuando se solicitan datos para una única coordenada. Si se superan los 512 puntos o coordenadas en los parámetros "locations" o "path", se devuelve una respuesta INVALID_REQUEST.

Respuestas de Elevation

Para cada solicitud válida, el servicio de Elevation devuelve una respuesta de Elevation en el formato indicado en la URL de la solicitud.

ElevationResponse

Campo Obligatorio Tipo Descripción
required Array<ElevationResult> Consulta ElevationResult para obtener más información.
required ElevationStatus Consulta ElevationStatus para obtener más información.
opcional string

Cuando el servicio devuelve un código de estado que no es OK, puede haber un campo error_message adicional dentro del objeto de respuesta. Este campo contiene información más detallada sobre los motivos del código de estado proporcionado. Este campo no siempre se devuelve y su contenido está sujeto a cambios.

ElevationStatus

Códigos de estado que devuelve el servicio.

  • OK: Indica que la solicitud a la API se realizó correctamente.
  • DATA_NOT_AVAILABLE que indica que no hay datos disponibles para las ubicaciones de entrada.
  • INVALID_REQUEST: Indica que la solicitud a la API tiene un formato incorrecto.
  • OVER_DAILY_LIMIT que indique cualquiera de las siguientes opciones:
    • Falta la clave de API o no es válida.
    • No se habilitó la facturación en tu cuenta.
    • Se superó un límite de uso autoimpuesto.
    • La forma de pago proporcionada ya no es válida (por ejemplo, venció una tarjeta de crédito).
  • OVER_QUERY_LIMIT: Indica que el solicitante superó la cuota.
  • REQUEST_DENIED: Indica que la API no completó la solicitud.
  • UNKNOWN_ERROR: Indica un error desconocido.

Cuando el código de estado es distinto de OK, puede haber un campo error_message adicional dentro del objeto de respuesta de Elevation. Este campo contiene información más detallada sobre los motivos del código de estado proporcionado.

La respuesta contiene un array results con los siguientes elementos:

ElevationResult

Campo Obligatorio Tipo Descripción
required número

La elevación de la ubicación en metros
required LatLngLiteral

Un elemento de ubicación de la posición para la que se calculan los datos de elevación Ten en cuenta que, para las solicitudes de ruta, el conjunto de elementos de ubicación contendrá los puntos de muestreo a lo largo de la ruta.

Consulta LatLngLiteral para obtener más información.

opcional número

Es el valor que indica la distancia máxima en metros entre los puntos de datos a partir de los cuales se interpoló la elevación. Esta propiedad estará ausente si se desconoce la resolución. Ten en cuenta que los datos de elevación se vuelven menos precisos (valores de resolución mayores) cuando se pasan varios puntos. Para obtener el valor de elevación más preciso para un punto, se deben realizar consultas independientes.

LatLngLiteral

Es un objeto que describe una ubicación específica con latitud y longitud en grados decimales.

Campo Obligatorio Tipo Descripción
required número

Latitud en grados decimales
required número

Longitud en grados decimales

Ejemplos de elevación posicional

En el siguiente ejemplo, se solicita la elevación de Denver, Colorado, la "ciudad a una milla de altura":

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>

En el siguiente ejemplo, se muestran varias respuestas (para Denver, Colorado, y para el Valle de la Muerte, California).

En esta solicitud, se muestra cómo usar la marca 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'

En esta solicitud, se muestra cómo usar la marca output de XML:

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

Selecciona las pestañas que aparecen a continuación para ver las respuestas de ejemplo en formato JSON y 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>

En los siguientes ejemplos, se solicitan datos de elevación a lo largo de una línea recta path desde el monte Whitney, California, hasta Badwater, California, los puntos más alto y más bajo de Estados Unidos continental. Solicitamos tres samples, por lo que se incluirán los dos extremos y el punto medio.

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>