Trang này được dịch bởi Cloud Translation API.

Yêu cầu và phản hồi về độ cao

Yêu cầu độ cao

Các yêu cầu API nâng cao được tạo dưới dạng một chuỗi URL. API trả về dữ liệu độ cao cho các vị trí trên trái đất. Bạn chỉ định dữ liệu vị trí theo một trong hai cách:

Dưới dạng một tập hợp gồm một hoặc nhiều locations.
Dưới dạng một chuỗi các điểm nối nhau dọc theo path.

Một trong hai phương pháp này sử dụng toạ độ vĩ độ/kinh độ để xác định vị trí hoặc đỉnh của đường dẫn. Tài liệu này mô tả định dạng bắt buộc của URL của API độ cao và các tham số có sẵn.

API Độ cao trả về dữ liệu cho các truy vấn một điểm với độ chính xác cao nhất có thể. Truy vấn theo lô liên quan đến nhiều vị trí có thể trả về dữ liệu với độ chính xác thấp hơn, đặc biệt nếu các vị trí trải rộng vì một số hoạt động làm mượt dữ liệu sẽ xảy ra.

Yêu cầu API Độ cao có dạng sau đây:

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

trong đó outputFormat có thể là một trong những giá trị sau:

json (được đề xuất), cho biết đầu ra trong Ký hiệu đối tượng JavaScript (JSON); hoặc
xml cho biết đầu ra ở định dạng XML, được gói trong một Nút <ElevationResponse>.

Lưu ý: URL phải được mã hoá đúng cách hợp lệ và bị giới hạn trong 16384 ký tự cho tất cả các dịch vụ web. Hãy lưu ý giới hạn này khi tạo URL của bạn. Xin lưu ý rằng các trình duyệt khác nhau, proxy và máy chủ cũng có thể có giới hạn ký tự URL khác nhau.

Bạn phải sử dụng HTTPS cho các yêu cầu sử dụng khoá API.

Yêu cầu thông số

Các yêu cầu tới API độ cao sử dụng nhiều tham số dựa trên việc yêu cầu là dành cho các vị trí riêng biệt hay dành cho một đường dẫn có thứ tự. Đối với các vị trí riêng biệt, yêu cầu trả lại độ cao dữ liệu về các vị trí cụ thể được chuyển trong yêu cầu; cho đường dẫn, thay vào đó, các yêu cầu độ cao sẽ được lấy mẫu dọc theo một đường dẫn nhất định.

Theo tiêu chuẩn trong tất cả các URL, các tham số được tách riêng bằng cách sử dụng ký tự dấu và (&). Danh sách thông số và các giá trị có thể có của chúng được trình bày dưới đây.

Tất cả yêu cầu

key – (bắt buộc) Khoá API. Khoá này xác định ứng dụng của bạn cho mục đích quản lý hạn mức. Tìm hiểu cách lấy khoá.

Yêu cầu về vị trí

locations (bắt buộc) xác định(các) vị trí trên trái đất để trả về dữ liệu độ cao. Thông số này sẽ lấy vị trí đơn lẻ dưới dạng một cặp {latitude,longitude} được phân tách bằng dấu phẩy (ví dụ: "40.714728,-73.998672") hoặc nhiều cặp vĩ độ/kinh độ được truyền dưới dạng mảng hoặc dưới dạng hình nhiều đường được mã hoá. Giới hạn là 512 điểm cho thông số cụ thể này. Để biết thêm thông tin, hãy xem phần Chỉ định vị trí bên dưới.

Yêu cầu về đường dẫn mẫu

path (bắt buộc) xác định đường dẫn trên trái đất cho để trả về dữ liệu độ cao. Tham số này xác định một tập hợp gồm hai hoặc các cặp {latitude,longitude} có thứ tự hơn xác định một con đường dọc theo bề mặt trái đất. Bạn phải dùng thông số này cùng với samples được mô tả bên dưới. Giới hạn là 512 điểm cho bài này tham số cụ thể. Để biết thêm thông tin, xem phần Chỉ định đường dẫn ở bên dưới.
samples (bắt buộc) chỉ định số lượng mẫu các điểm dọc theo một đường dẫn để trả về dữ liệu độ cao. Chiến lược phát hành đĩa đơn Tham số samples chia path đã cho thành một tập hợp có thứ tự các điểm cách đều nhau dọc theo đường đi.

Chỉ định vị trí

Yêu cầu về vị trí được biểu thị thông qua việc sử dụng Tham số locations, cho biết các yêu cầu về độ cao cho các vị trí cụ thể được chuyển qua vĩ độ/kinh độ.

Tham số locations có thể lấy những giá trị sau đối số:

Một toạ độ duy nhất: locations=40.714728,-73.998672
Một mảng toạ độ được phân tách bằng dấu gạch đứng ("|") ký tự: locations=40.714728,-73.998672|-34.397,150.644
Một tập hợp toạ độ được mã hoá bằng Đã mã hoá Thuật toán đa dòng: locations=enc:gfo}EtohhU

Chuỗi toạ độ kinh độ và vĩ độ được xác định bằng các chữ số trong chuỗi văn bản được phân tách bằng dấu phẩy. Ví dụ: "40.714728,-73.998672" là giá trị locations hợp lệ. Vĩ độ và giá trị kinh độ phải tương ứng với một vị trí hợp lệ trên bề mặt trái đất. Vĩ độ có thể lấy bất kỳ giá trị nào trong khoảng -90 và 90 trong khi các giá trị kinh độ có thể lấy bất kỳ giá trị nào từ -180 đến 180. Nếu bạn chỉ định kinh độ hoặc vĩ độ không hợp lệ, yêu cầu của bạn sẽ bị từ chối là một yêu cầu không hợp lệ.

Bạn có thể chuyển tối đa 512 toạ độ trong một mảng hoặc được mã hoá hình nhiều đường mà vẫn tạo được URL hợp lệ. Lưu ý rằng khi truyền nhiều toạ độ, độ chính xác của bất kỳ dữ liệu nào được trả về có thể có độ phân giải thấp hơn so với khi yêu cầu dữ liệu cho một toạ độ. Vượt quá 512 điểm hoặc toạ độ trong "vị trí" hoặc "path" tham số trả về một giá trị INVALID_REQUEST phản hồi.

Chỉ định đường dẫn

Các yêu cầu về đường dẫn mẫu được biểu thị bằng cách sử dụng path và tham số samples, cho biết yêu cầu cung cấp dữ liệu độ cao dọc theo một đường dẫn tại các khoảng thời gian xác định. Giống như với yêu cầu vị trí, việc sử dụng Tham số locations, tham số path chỉ định một tập hợp các giá trị vĩ độ và kinh độ. Tuy nhiên, không giống như yêu cầu vị trí path chỉ định một tập hợp các đỉnh có thứ tự. Thay vì trả lại chỉ dữ liệu độ cao tại các đỉnh, yêu cầu đường dẫn sẽ được lấy mẫu dọc theo độ dài của đường dẫn, dựa trên số lượng samples được chỉ định (bao gồm các điểm cuối).

Tham số path có thể lấy một trong hai giá trị sau đối số:

Một mảng gồm hai hoặc nhiều chuỗi văn bản toạ độ được phân tách bằng dấu phẩy được phân tách bằng dấu gạch đứng ("|") ký tự: path=40.714728,-73.998672|-34.397,150.644
Toạ độ được mã hoá bằng cách sử dụng Đã mã hoá Thuật toán đa dòng: path=enc:gfo}EtohhUxD@bAxJmGF

Chuỗi toạ độ kinh độ và vĩ độ được xác định bằng các chữ số trong chuỗi văn bản được phân tách bằng dấu phẩy. Ví dụ: "40.714728,-73.998672|-34.397, 150.644" là một hợp lệ Giá trị path. Các giá trị vĩ độ và kinh độ phải tương ứng với nhau tại vị trí hợp lệ trên bề mặt trái đất. Vĩ độ có thể lấy bất kỳ giá trị nào trong khoảng -90 và 90 trong khi các giá trị kinh độ có thể lấy bất kỳ giá trị nào từ -180 đến 180. Nếu bạn chỉ định kinh độ hoặc vĩ độ không hợp lệ, yêu cầu của bạn sẽ bị từ chối là một yêu cầu không hợp lệ.

Bạn có thể chuyển tối đa 512 toạ độ trong một mảng hoặc được mã hoá hình nhiều đường mà vẫn tạo được URL hợp lệ. Lưu ý rằng khi chuyển nhiều toạ độ, thì độ chính xác của mọi dữ liệu được trả về đều có thể có độ phân giải thấp hơn khi yêu cầu dữ liệu cho một toạ độ. Vượt quá 512 điểm hoặc toạ độ trong "vị trí" hoặc "path" tham số trả về phản hồi INVALID_REQUEST.

Phản hồi về độ cao

Đối với mỗi yêu cầu hợp lệ, dịch vụ Độ cao sẽ trả về Độ cao theo định dạng được chỉ định trong URL yêu cầu.

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.

Khi mã trạng thái không phải là OK, có thể có thêm Trường error_message trong đối tượng phản hồi Độ cao. Trường này chứa nhiều thông tin chi tiết về lý do tạo ra một mã trạng thái cụ thể.

Phản hồi chứa một mảng results với các phần tử sau:

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.

Đối tượng location có các phần tử sau:

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

Ví dụ về độ cao vị trí

Ví dụ sau đây yêu cầu độ cao cho Denver, Colorado, "Thành phố núi cao" ở định dạng 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>

Ví dụ sau đây hiển thị nhiều câu trả lời (cho Denver, CO và Thung lũng Chết, tiểu bang California).

Yêu cầu này minh hoạ cách sử dụng cờ 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'

Yêu cầu này minh hoạ cách sử dụng cờ XML output:

https://maps.googleapis.com/maps/api/elevation/xml?locations=39.7391536,-104.9847034|36.455556,-116.866667&key=YOUR_API_KEY

Chọn các thẻ bên dưới để xem phản hồi JSON và XML mẫu.

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>

Các ví dụ sau đây yêu cầu cung cấp dữ liệu về độ cao dọc theo một đường thẳng path từ Núi Whitney, CA đến Badwater, CA, nơi cao nhất và điểm thấp nhất trên lục địa Hoa Kỳ. Chúng tôi yêu cầu ba samples, nên sẽ bao gồm hai điểm cuối và điểm giữa chừng.

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>

Yêu cầu và phản hồi về độ cao

Yêu cầu độ cao

Yêu cầu thông số

Tất cả yêu cầu

Yêu cầu về vị trí

Yêu cầu về đường dẫn mẫu

Chỉ định vị trí

Chỉ định đường dẫn

Phản hồi về độ cao

ElevationResponse

`results`

`status`

`error_message`

ElevationStatus

ElevationResult

`elevation`

`location`

`resolution`

LatLngLiteral

`lat`

`lng`

Ví dụ về độ cao vị trí

URL

cURL

JSON

XML

URL

cURL

JSON

XML

URL

cURL

JSON

XML