Эта страница переведена с помощью Cloud Translation API.

Запросы и ответы на повышение

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

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

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

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

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

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

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

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

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

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

Для запросов, использующих ключ API, требуется HTTPS.

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

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

Как это принято во всех 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

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

В массиве или закодированной полилинии можно передать до 512 координат, при этом будет сформирован действительный URL-адрес. Обратите внимание, что при передаче нескольких координат точность возвращаемых данных может быть ниже, чем при запросе данных для одной координаты. Превышение 512 точек или координат в параметрах 'locations' или 'path' приводит к ответу 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 Если вы укажете недопустимое значение широты или долготы, ваш запрос будет отклонен как некорректный.

Реакции на изменение высоты

Массив из двух или более текстовых строк с координатами, разделенных запятыми символом вертикальной черты (' | '): 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 возвращает ответ Elevation в формате, указанном в URL-адресе запроса.

ElevationResponse

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

Статус высоты

Коды состояния, возвращаемые службой.

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 со следующими элементами:

Результат высоты

Поле	Необходимый	Тип	Описание
`elevation`	необходимый	число	Высота местности в метрах.
`location`	необходимый	LatLngLiteral	Элемент местоположения, содержащий информацию о позиции, для которой вычисляются данные о высоте. Обратите внимание, что для запросов маршрута набор элементов местоположения будет содержать точки, выбранные для расчета вдоль маршрута. Дополнительную информацию см. в разделе 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>

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

Этот запрос демонстрирует использование флага output JSON:

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'

Этот запрос демонстрирует использование флага output XML:

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>

Запросы и ответы на повышение

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

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

Все запросы

Позиционные запросы

Запросы на выборку пути

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

Укажите пути

Реакции на изменение высоты

Реакции на изменение высоты

ElevationResponse

`results`

`status`

`error_message`

Статус высоты

Результат высоты

`elevation`

`location`

`resolution`

LatLngLiteral

`lat`

`lng`

Примеры позиционного повышения

URL

cURL

JSON

XML

URL

cURL

JSON

XML

URL

cURL

JSON

XML

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

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

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

Все запросы

Позиционные запросы

Запросы на выборку пути

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

Укажите пути

Реакции на изменение высоты

Реакции на изменение высоты

ElevationResponse

results

status

error_message

Статус высоты

Результат высоты

elevation

location

resolution

LatLngLiteral

lat

lng

Примеры позиционного повышения

URL

cURL

JSON

XML

URL

cURL

JSON

XML

URL

cURL

JSON

XML

Запросы и ответы на повышение

`results`

`status`

`error_message`

`elevation`

`location`

`resolution`

`lat`

`lng`