고도 요청 및 응답

고도 요청

Elevation API 요청은 URL 문자열로 구성됩니다. 이 API는 지구상의 위치에 대한 고도 데이터를 반환합니다. 위치 데이터는 다음 두 가지 방법 중 하나로 지정할 수 있습니다.

  • 하나 이상의 locations 집합으로
  • path을 따라 연결된 일련의 점으로 표시됩니다.

두 접근 방식 모두 위도/경도 좌표를 사용하여 위치 또는 경로 정점을 식별합니다. 이 문서에서는 Elevation API URL의 필수 형식과 사용 가능한 매개변수를 설명합니다.

Elevation API는 가능한 한 가장 높은 정확도의 단일 지점 쿼리에 대한 데이터를 반환합니다. 여러 위치가 포함된 일괄 쿼리는 데이터가 다소 평활화되므로 특히 위치가 멀리 떨어져 있는 경우 정확도가 떨어진 데이터를 반환할 수 있습니다.

Elevation API 요청의 형식은 다음과 같습니다.

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

여기서 outputFormat는 다음 값 중 하나일 수 있습니다.

  • json (권장): JavaScript 객체 표기법 (JSON)으로 된 출력을 나타냅니다.
  • xml: XML의 출력을 나타내며 <ElevationResponse> 노드 내에 래핑됩니다.

참고: URL이 유효하려면 올바르게 인코딩되어야 하며 모든 웹 서비스의 경우 16,384자(영문 기준)로 제한됩니다. URL을 구성할 때 이 한도에 유의하세요. 브라우저, 프록시, 서버에 따라 URL 문자 수 한도가 다를 수 있습니다.

HTTPS는 API 키를 사용하는 요청에 필요합니다.

요청 매개변수

Elevation API에 대한 요청은 개별 위치에 대한 요청인지 순서가 지정된 경로에 대한 요청인지에 따라 다른 매개변수를 사용합니다. 개별 위치의 경우 고도 요청은 요청에 전달된 특정 위치의 데이터를 반환합니다. 경로의 경우 고도 요청은 대신 지정된 경로를 따라 샘플링됩니다.

모든 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 값입니다. 위도와 경도 값은 지구 표면의 유효한 위치에 해당해야 합니다. 위도 값은 -9090 사이의 값을 취할 수 있으며 경도 값은 -180180 사이의 값을 취할 수 있습니다. 잘못된 위도 또는 경도 값을 지정하면 요청이 잘못된 요청으로 거부됩니다.

유효한 URL을 구성하면서 배열 또는 인코딩된 다중선 내에서 최대 512개의 좌표를 전달할 수 있습니다. 여러 좌표를 전달하는 경우 반환되는 데이터의 정확도가 단일 좌표에 대해 데이터를 요청할 때보다 낮을 수도 있습니다. '위치' 또는 '경로' 매개변수의 지점 또는 좌표가 512개를 초과하면 INVALID_REQUEST 응답이 반환됩니다.

경로 지정

샘플링된 경로 요청은 pathsamples 매개변수를 사용하여 지정된 간격으로 경로의 고도 데이터 요청을 나타냅니다. locations 매개변수를 사용하는 위치 요청과 마찬가지로 path 매개변수는 경도 및 위도 값의 집합을 지정합니다. 하지만 위치 지정 요청과 달리 path는 순서가 지정된 꼭짓점의 집합을 지정합니다. 경로 요청은 꼭짓점에서만 고도 데이터를 반환하는 대신 지정된 samples 수 (끝점을 포함)에 따라 경로의 길이를 따라 샘플링됩니다.

path 매개변수는 다음 인수 중 하나를 사용할 수 있습니다.

  • 쉼표로 구분된 2개 이상의 좌표 텍스트 문자열 배열로, 파이프(|) 문자(path=40.714728,-73.998672|-34.397,150.644)를 사용하여 구분됩니다.
  • 인코딩된 폴리라인 알고리즘을 사용하여 인코딩된 좌표: path=enc:gfo}EtohhUxD@bAxJmGF

위도 및 경도 좌표 문자열은 쉼표로 구분된 텍스트 문자열 내에서 숫자를 사용하여 정의됩니다. 예를 들어 '40.714728,-73.998672|-34.397, 150.644'는 유효한 path 값입니다. 위도 및 경도 값은 지구 표면의 유효한 위치에 해당해야 합니다. 위도 값은 -9090 사이의 값을 취할 수 있으며 경도 값은 -180180 사이의 값을 취할 수 있습니다. 잘못된 위도 또는 경도 값을 지정하면 요청이 잘못된 요청으로 거부됩니다.

유효한 URL을 구성하면서 배열 또는 인코딩된 다중선 내에서 최대 512개의 좌표를 전달할 수 있습니다. 여러 좌표를 전달하는 경우 반환되는 데이터의 정확도가 단일 좌표에 대해 데이터를 요청할 때보다 낮을 수도 있습니다. 'locations' 또는 'path' 매개변수의 지점 또는 좌표가 512개를 초과하면 INVALID_REQUEST 응답이 반환됩니다.

고도 응답

각각의 유효한 요청에 대해 고도 서비스는 요청 URL에 표시된 형식으로 고도 응답을 반환합니다.

ElevationResponse

FieldRequiredTypeDescription
required Array<ElevationResult> See ElevationResult for more information.
requiredElevationStatus 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
requirednumber

The elevation of the location in meters.

requiredLatLngLiteral

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
requirednumber

Latitude in decimal degrees

requirednumber

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>

다음 예는 여러 응답 (콜로라도주 덴버 및 캘리포니아주 데스밸리)을 보여줍니다.

이 요청은 JSON output 플래그를 사용하는 방법을 보여줍니다.

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'

이 요청은 XML output 플래그를 사용하는 방법을 보여줍니다.

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>