Запросы на повышение прав
Запросы 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-адресах, параметры разделяются символом амперсанда ( &
). Список параметров и их возможные значения указаны ниже.
Все запросы
-
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
Field | Required | Type | Description |
---|---|---|---|
| required | Array< ElevationResult > | See ElevationResult for more information. |
| required | ElevationStatus | See ElevationStatus for more information. |
| optional | string |
When the service returns a status code other than |
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 |
---|---|---|---|
| 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. |
| 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 |
---|---|---|---|
| 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>