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

Yêu cầu về độ cao

Các yêu cầu Elevation API được tạo dưới dạng một chuỗi URL. API này 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:

  • Là một tập hợp gồm một hoặc nhiều locations.
  • Là một chuỗi các điểm được kết nối dọc theo một path.

Cả hai phương pháp này đều 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 Elevation API và các tham số có sẵn.

Elevation API trả về dữ liệu cho các truy vấn một điểm có độ chính xác cao nhất có thể. Các truy vấn hàng loạt liên quan đến nhiều vị trí có thể trả về dữ liệu kém chính xác hơn, đặc biệt nếu các vị trí nằm rải rác, vì một số dữ liệu được làm mịn.

Yêu cầu Elevation API có dạng như sau:

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

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

  • json (nên dùng), cho biết đầu ra ở định dạng JavaScript Object Notation (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 thì mới hợp lệ và có tối đa 16.384 ký tự cho tất cả các dịch vụ web. Hãy lưu ý đến giới hạn này khi tạo URL. Xin lưu ý rằng các trình duyệt, proxy và máy chủ khác nhau cũng có thể có giới hạn ký tự URL khác nhau.

HTTPS là giao thức bắt buộc đối với các yêu cầu sử dụng khoá API.

Tham số yêu cầu

Các yêu cầu đến Elevation API sử dụng các tham số khác nhau, tuỳ thuộc vào việc yêu cầu là cho các vị trí rời rạc hay cho một đường dẫn có thứ tự. Đối với các vị trí rời rạc, yêu cầu về độ cao sẽ trả về dữ liệu về các vị trí cụ thể được truyền trong yêu cầu; đối với các đường dẫn, yêu cầu về độ cao sẽ được lấy mẫu dọc theo đường dẫn đã cho.

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

Tất cả yêu cầu

  • key – (bắt buộc) Khoá API của ứng dụng. 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. Tham số này nhận một vị trí duy nhất dưới dạng 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ột mảng hoặc dưới dạng một đường nhiều đường được mã hoá. Tham số cụ thể này có giới hạn là 512 điểm. Để 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 được lấy mẫu

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

Chỉ định vị trí

Các yêu cầu về vị trí được chỉ định thông qua việc sử dụng tham số locations, cho biết các yêu cầu về độ cao cho những vị trí cụ thể được truyền dưới dạng giá trị vĩ độ/kinh độ.

Tham số locations có thể nhận các đối số sau:

  • Một toạ độ duy nhất: locations=40.714728,-73.998672
  • Một mảng các toạ độ được phân tách bằng ký tự sổ thẳng ("|"): locations=40.714728,-73.998672|-34.397,150.644
  • Một tập hợp các toạ độ được mã hoá bằng Thuật toán đường nhiều đoạn được mã hoá: locations=enc:gfo}EtohhU

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

Bạn có thể truyền tối đa 512 toạ độ trong một mảng hoặc đường nhiều đoạn được mã hoá, trong khi vẫn tạo một URL hợp lệ. Xin lưu ý rằng khi truyền nhiều toạ độ, độ chính xác của mọi dữ liệu đượ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ạ độ duy nhất. Việc vượt quá 512 điểm hoặc toạ độ trong các tham số "locations" hoặc "path" sẽ trả về một phản hồi INVALID_REQUEST.

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

Các yêu cầu về đường dẫn được lấy mẫu được biểu thị thông qua việc sử dụng các tham số pathsamples, cho biết yêu cầu về dữ liệu độ cao dọc theo một đường dẫn ở các khoảng thời gian đã chỉ định. Tương tự như các yêu cầu theo vị trí bằng cách 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ề vị trí, path chỉ định một tập hợp các đỉnh có thứ tự. Thay vì chỉ trả về dữ liệu độ cao tại các đỉnh, các yêu cầu về đường dẫn được lấy mẫu dọc theo chiều dài của đường dẫn, dựa trên số lượng samples được chỉ định (bao gồm cả các điểm cuối).

Tham số path có thể nhận một trong các đối số sau:

  • 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 ký tự dấu gạch đứng ("|"): path=40.714728,-73.998672|-34.397,150.644
  • Toạ độ được mã hoá bằng Thuật toán đường đa tuyến được mã hoá: path=enc:gfo}EtohhUxD@bAxJmGF

Chuỗi toạ độ vĩ độ và kinh độ được xác định bằng các chữ số trong một 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 giá trị path hợp lệ. Giá trị vĩ độ và 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ể nhận bất kỳ giá trị nào trong khoảng từ -90 đến 90, trong khi giá trị kinh độ có thể nhận bất kỳ giá trị nào trong khoảng từ -180 đến 180. Nếu bạn chỉ định một giá trị vĩ độ hoặc kinh độ không hợp lệ, thì yêu cầu của bạn sẽ bị từ chối vì là yêu cầu không hợp lệ.

Bạn có thể truyền tối đa 512 toạ độ trong một mảng hoặc đường nhiều đoạn được mã hoá, trong khi vẫn tạo một URL hợp lệ. Xin lưu ý rằng khi truyền nhiều toạ độ, độ chính xác của mọi dữ liệu đượ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ạ độ duy nhất. Việc vượt quá 512 điểm hoặc toạ độ trong các tham số "locations" hoặc "path" sẽ trả về một phản hồi INVALID_REQUEST.

Câu trả lời về độ cao

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

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.

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 thông tin chi tiết hơn về lý do đằng sau mã trạng thái đã cho.

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

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.

Đố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.

FieldRequiredTypeDescription
requirednumber

Latitude in decimal degrees

requirednumber

Longitude in decimal degrees

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

Ví dụ sau đây yêu cầu độ cao của Denver, Colorado, "Thành phố cao một dặm" ở đị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 cho thấy nhiều phản hồi (cho Denver, Colorado và Thung lũng Chết, 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ờ output XML:

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 dữ liệu độ cao dọc theo một đường thẳng path từ Mt. Whitney, California đến Badwater, California, điểm cao nhất và thấp nhất ở lục địa Hoa Kỳ. Chúng ta yêu cầu 3 samples, vì vậy, số này sẽ bao gồm 2 điểm cuối và điểm giữa.

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>