Эта страница переведена с помощью 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 Если вы укажете недопустимое значение широты или долготы, ваш запрос будет отклонен как некорректный.

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

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

ElevationResponse

Field	Required	Type	Description
`results`	required	Array< ElevationResult >	See ElevationResult for more information.
`status`	required	ElevationStatus	See ElevationStatus for more information.
`error_message`	optional	string	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.

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

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

ElevationResult

Field	Required	Type	Description
`elevation`	required	number	The elevation of the location in meters.
`location`	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.
`resolution`	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.

Объект location содержит следующие элементы:

LatLngLiteral

An object describing a specific location with Latitude and Longitude in decimal degrees.

Field	Required	Type	Description
`lat`	required	number	Latitude in decimal degrees
`lng`	required	number	Longitude in decimal degrees

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

В следующем примере запрашивается высота над уровнем моря для Денвера, штат Колорадо, «города на высоте мили», в формате 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>

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

Этот запрос демонстрирует использование флага 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`

ElevationStatus

ElevationResult

`elevation`

`location`

`resolution`

LatLngLiteral

`lat`

`lng`

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

URL

cURL

JSON

XML

URL

cURL

JSON

XML

URL

cURL

JSON

XML

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

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

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

Все запросы

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

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

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

Указание путей

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

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

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

`results`

`status`

`error_message`

`elevation`

`location`

`resolution`

`lat`

`lng`