Чтобы переводить контент на ваш предпочитаемый язык, Google использует технологии на основе искусственного интеллекта. Переводы от ИИ могут содержать ошибки.

Запросы и ответы Elevation API

Запросы данных о высоте

Запросы к Elevation API создаются в виде строки URL. API возвращает данные о высоте точек на земной поверхности. Указать данные о местоположении можно одним из двух способов:

в виде набора из одного или нескольких объектов locations.
В виде последовательности соединенных точек вдоль пути (path).

В обоих случаях для определения местоположений или вершин маршрута используются координаты широты и долготы. В этом документе описаны обязательный формат URL Elevation API и доступные параметры.

Elevation API возвращает данные для запросов по одной точке с максимально возможной точностью. Пакетные запросы, включающие несколько местоположений, могут возвращать менее точные данные, особенно если местоположения находятся далеко друг от друга, поскольку происходит некоторое сглаживание данных.

Запрос к Elevation API имеет следующий формат:

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

где outputFormat может принимать одно из следующих значений:

json (рекомендуется) – указывает, что выходные данные должны быть в формате JavaScript Object Notation (JSON);
xml – указывает, что выходные данные должны быть в формате XML и заключены в узел <ElevationResponse>.

Примечание. Чтобы URL был действительным, он должен быть правильно закодирован. Для всех веб-сервисов длина URL не должна превышать 16 384 символа. Учитывайте это ограничение при создании URL. Обратите внимание, что в разных браузерах, прокси-серверах и серверах могут быть разные ограничения на количество символов в URL.

Протокол HTTPS является обязательным для запросов с ключом API.

Параметры запроса

В запросах к Elevation API используются разные параметры в зависимости от того, запрашиваются ли данные для отдельных местоположений или для упорядоченного маршрута. Для отдельных местоположений запросы высоты возвращают данные по конкретным местоположениям, переданным в запросе. Для путей запросы высоты выбираются вдоль заданного пути.

Параметры разделяются амперсандами (&) в соответствии со стандартом написания URL. Список параметров и их возможных значений приведен ниже.

Все запросы

key – ключ API вашего приложения (обязательный параметр). Этот ключ идентифицирует ваше приложение для управления квотами. Подробнее о том, как получить ключ…

Запросы с позиционированием

locations (обязательный параметр) задает одну или несколько точек на земной поверхности, высоту которых требуется получить. Этот параметр принимает либо одно местоположение в виде пары {широта,долгота}, разделенной запятой (например, "40.714728,-73.998672"), либо несколько пар широты и долготы, переданных в виде массива или закодированной ломаной линии. Для этого параметра установлено ограничение в 512 точек. Подробнее о том, как указать местоположения…

Запросы данных о высоте по контрольным точкам пути

path (обязательный параметр) определяет путь на земной поверхности, для которого требуются данные о высоте. Этот параметр определяет набор из двух или более упорядоченных пар {широта,долгота}, задающих путь по поверхности Земли. Этот параметр необходимо использовать вместе с параметром samples, описанным ниже. Для этого параметра установлено ограничение в 512 точек. Подробная информация приведена в разделе Указание путей ниже.
samples (обязательный параметр) указывает количество контрольных точек вдоль пути, для которого требуется получить данные о высоте. Параметр samples делит заданный параметром path путь на отрезки из ряда равноудаленных точек.

Укажите местоположения

Запросы для отдельных точек обозначаются параметром locations, который указывает, что запрашиваются данные о высоте для определенных местоположений, переданных в виде значений широты и долготы.

Параметр locations может принимать следующие аргументы:

Одна координата: locations=40.714728,-73.998672
Массив координат, разделенных вертикальной чертой (|): locations=40.714728,-73.998672|-34.397,150.644
Набор закодированных координат, использующих алгоритм кодированной ломаной линии: locations=enc:gfo}EtohhU

Координаты широты и долготы задаются в виде чисел в текстовой строке, разделенных запятой. Пример допустимого значения locations: "40.714728,-73.998672". Значения широты и долготы должны соответствовать действительному местоположению на Земле. Широта может принимать любое значение от -90 до 90, а долгота – от -180 до 180. Если вы укажете недопустимое значение широты или долготы, ваш запрос будет отклонен как недопустимый.

В массиве или закодированной ломаной линии можно передать до 512 координат, чтобы URL оставался действительным. Обратите внимание, что при передаче координат нескольких точек точность полученных данных может быть ниже, чем при запросе данных для одной точки. Если в параметре locations или path указано более 512 точек или координат, возвращается ответ INVALID_REQUEST.

Укажите пути

Запросы выборки данных о высоте для точек пути обозначаются параметрами path и samples, которые указывают на запрос данных о высоте для точек пути с заданными интервалами. Как и в запросах для отдельных точек locations, параметр path указывает набор значений широты и долготы. Однако, в отличие от запросов для отдельных точек, в параметре path указывается упорядоченный набор вершин ломаной кривой. Запрос пути не просто возвращает данные о высоте в каждой вершине. Производится выборка вдоль пути, где все контрольные точки равноудалены друг от друга (включая конечные точки). Количество точек определяется параметром samples.

Параметр path может принимать один из следующих аргументов:

Массив из двух или более текстовых строк с координатами, разделенными запятыми. Сами строки разделяются вертикальной чертой (|): path=40.714728,-73.998672|-34.397,150.644
Закодированные координаты с использованием алгоритма кодированной ломаной линии: path=enc:gfo}EtohhUxD@bAxJmGF

Строки координат широты и долготы определяются с помощью чисел в текстовой строке, разделенной запятыми. Например, "40.714728,-73.998672|-34.397, 150.644" – допустимое значение path. Значения широты и долготы должны соответствовать действительному местоположению на поверхности Земли. Широта может принимать любое значение от -90 до 90, а долгота – от -180 до 180. Если вы укажете недопустимое значение широты или долготы, ваш запрос будет отклонен как недействительный.

В массиве или закодированной ломаной линии можно передать до 512 координат, не нарушая структуру URL. Обратите внимание, что при передаче координат нескольких точек точность полученных данных может быть ниже, чем при запросе данных для одной точки. Если в параметре locations или path указано более 512 точек или координат, возвращается ответ INVALID_REQUEST.

Ответы на запросы о высоте

Массив из двух или более текстовых строк с координатами, разделенными запятыми. Сами строки разделяются вертикальной чертой (|): path=40.714728,-73.998672|-34.397,150.644
Закодированные координаты с использованием алгоритма кодированной ломаной линии: path=enc:gfo}EtohhUxD@bAxJmGF

Строки координат широты и долготы определяются с помощью чисел в текстовой строке, разделенной запятыми. Например, "40.714728,-73.998672|-34.397, 150.644" – допустимое значение path. Значения широты и долготы должны соответствовать действительному местоположению на поверхности Земли. Широта может принимать любое значение от -90 до 90, а долгота – от -180 до -180. Если вы укажете недопустимое значение широты или долготы, ваш запрос будет отклонен как недействительный.

Ответы на запросы о высоте

Для каждого допустимого запроса сервис Elevation возвращает ответ в формате, указанном в URL запроса.

ElevationResponse

Поле	Обязательно	Тип	Описание
`results`	Обязательно	Массив<ElevationResult>	Дополнительную информацию можно найти в описании ElevationResult.
`status`	Обязательно	ElevationStatus	Дополнительную информацию можно найти в разделе ElevationStatus.
`error_message`	необязательно	string	Если сервис возвращает код статуса, отличный от `OK`, в объекте ответа может присутствовать дополнительное поле `error_message`. В этом поле содержится более подробная информация о причинах, по которым был присвоен тот или иной код статуса. Это поле возвращается не всегда, и его содержимое может меняться.

ElevationStatus

Коды статуса, возвращаемые сервисом.

OK означает, что запрос к API успешно выполнен;
DATA_NOT_AVAILABLE. Это означает, что для указанных местоположений нет данных.
INVALID_REQUEST означает, что запрос к API сформирован неправильно.
OVER_DAILY_LIMIT, указывающие на любое из следующего:
- Ключ API отсутствует или недействителен.
- В вашем аккаунте не включены платежные функции.
- Превышено заданное ограничение на использование.
- Указанный способ оплаты больше не действует (например, истек срок действия кредитной карты).
OVER_QUERY_LIMIT означает, что запрашивающее приложение превысило квоту;
REQUEST_DENIED означает, что API не выполнил запрос.
UNKNOWN_ERROR означает неизвестную ошибку.

Если код статуса не равен OK, в объекте ответа Elevation может присутствовать дополнительное поле error_message. В этом поле содержится более подробная информация о причинах, по которым был присвоен тот или иной код статуса.

Ответ содержит массив results со следующими элементами:

ElevationResult

Поле	Обязательно	Тип	Описание
`elevation`	Обязательно	число	Высота точки над уровнем моря в метрах.
`location`	Обязательно	LatLngLiteral	Элемент location той точки, для которой вычисляются данные о высоте. Обратите внимание, что для запросов пути набор элементов location будет содержать контрольные точки вдоль пути. Подробную информацию можно найти в разделе LatLngLiteral.
`resolution`	необязательно	число	Значение, указывающее максимальное расстояние (в метрах) между точками данных, на основании которых интерполируется значение высоты. Если разрешение неизвестно, это свойство отсутствует. Обратите внимание, что если передается много точек, точность высотных данных снижается (более высокие значения разрешения). Чтобы получить максимально точное значение высоты для точки, следует запрашивать его независимо от других точек.

LatLngLiteral

Объект, описывающий определенное местоположение с помощью широты и долготы в десятичных градусах.

Поле	Обязательно	Тип	Описание
`lat`	Обязательно	число	Широта в десятичных градусах
`lng`	Обязательно	число	Долгота в десятичных градусах

Примеры высоты для отдельных точек

В следующем примере запрашивается высота над уровнем моря для Денвера (штат Колорадо), который называют "городом на высоте мили":

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>

В примере ниже показано несколько ответов (для Денвера, штат Колорадо, и Долины Смерти, штат Калифорния).

В этом запросе используется флаг 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'

В этом запросе используется XML-флаг output:

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

Чтобы посмотреть примеры ответов в форматах JSON и 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>

В примере ниже запрашиваются данные о высоте вдоль прямой линии path от горы Уитни до впадины Бэдуотер в Калифорнии – самой высокой и самой низкой точек в континентальной части США. Мы запрашиваем три samples, поэтому в ответ будут включены две конечные точки и средняя точка.

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>

Запросы и ответы Elevation API

Запросы данных о высоте

Параметры запроса

Все запросы

Запросы с позиционированием

Запросы данных о высоте по контрольным точкам пути

Укажите местоположения

Укажите пути

Ответы на запросы о высоте

Ответы на запросы о высоте

ElevationResponse

`results`

`status`

`error_message`

ElevationStatus

ElevationResult

`elevation`

`location`

`resolution`

LatLngLiteral

`lat`

`lng`

Примеры высоты для отдельных точек

URL

cURL

JSON

XML

URL

cURL

JSON

XML

URL

cURL

JSON

XML

Запросы и ответы Elevation API Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.

Запросы данных о высоте

Параметры запроса

Все запросы

Запросы с позиционированием

Запросы данных о высоте по контрольным точкам пути

Укажите местоположения

Укажите пути

Ответы на запросы о высоте

Ответы на запросы о высоте

ElevationResponse

results

status

error_message

ElevationStatus

ElevationResult

elevation

location

resolution

LatLngLiteral

lat

lng

Примеры высоты для отдельных точек

URL

cURL

JSON

XML

URL

cURL

JSON

XML

URL

cURL

JSON

XML

Запросы и ответы Elevation API

`results`

`status`

`error_message`

`elevation`

`location`

`resolution`

`lat`

`lng`