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

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

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

Запросы Elevation API формируются как строка 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 , может быть дополнительное поле error_message в объекте ответа Elevation. Это поле содержит более подробную информацию о причинах данного кода статуса.

Ответ содержит массив 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`