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

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

Запросы на высоту

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

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

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

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

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

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

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

json (рекомендуется), указывает вывод в формате JavaScript Object Notation (JSON); или
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`