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

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

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

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

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

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

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

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

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

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

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

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

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

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

Как обычно во всех URL-адресах, параметры разделяются символом амперсанда ( &amp; ). Список параметров и их возможные значения указаны ниже.

Все запросы

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

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

Реакция на высоту

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

ElevationResponse

FieldRequiredTypeDescription
required Array< ElevationResult > See ElevationResult for more information.
required ElevationStatus See ElevationStatus for more information.
optionalstring

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

FieldRequiredTypeDescription
required number

The elevation of the location in meters.

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.

optionalnumber

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.

FieldRequiredTypeDescription
required number

Latitude in decimal degrees

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 -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 -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 -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>