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

Yêu cầu về độ cao

Yêu cầu Elevation API được tạo dưới dạng 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:

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 được kết nối dọc theo path.

Cả hai phương pháp này đều sử dụng toạ độ vĩ độ/kinh độ để xác định vị trí hoặc đỉnh đườ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 có độ chính xác thấp hơn, đặc biệt là nếu các vị trí nằm cách xa nhau, vì một số dữ liệu được làm mượt.

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

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

trong đó outputFormat có thể là một trong các 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 <ElevationResponse> nút.

Lưu ý: URL phải được mã hoá đúng cách để hợp lệ và bị giới hạn ở 16384 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.

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

Các tham số trong yêu cầu

Các yêu cầu gửi đến Elevation API 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 cho một đường dẫn có thứ tự. Đối với các vị trí riêng biệt, 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à (&). Danh sách tham số và các giá trị có thể có của chúng đượ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 mà 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 {vĩ độ,kinh độ} đượ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 đường nhiều đoạn đượ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 mà từ đó trả về dữ liệu độ cao. Tham số này xác định một tập hợp gồm 2 cặp {vĩ độ,kinh độ} có thứ tự trở lên, 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ố điểm mẫu dọc theo một đường dẫn mà từ đó 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í

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 yêu cầu về độ cao cho các 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 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 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ách sử dụ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 dưới dạng 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ề phản hồi INVALID_REQUEST.

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

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ố path và samples, cho biết yêu cầu về dữ liệu độ cao dọc theo một đường dẫn theo các khoảng thời gian đã chỉ định. Giống như yêu cầu về vị trí 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 2 chuỗi văn bản toạ độ được phân tách bằng dấu phẩy trở lên, được phân tách bằng ký tự sổ thẳng ('|'): path=40.714728,-73.998672|-34.397,150.644
Toạ độ được mã hoá bằng Thuật toán đường nhiều đoạn được mã hoá: path=enc:gfo}EtohhUxD@bAxJmGF

Chuỗi toạ độ vĩ độ và kinh độ được xác định bằng cách sử dụ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 dưới dạng yêu cầu không hợp lệ.

Phản hồi về độ cao

Một mảng gồm 2 chuỗi văn bản toạ độ được phân tách bằng dấu phẩy trở lên, được phân tách bằng ký tự sổ thẳng ('|'): path=40.714728,-73.998672|-34.397,150.644
Toạ độ được mã hoá bằng Thuật toán đường nhiều đoạn được mã hoá: path=enc:gfo}EtohhUxD@bAxJmGF

Chuỗi toạ độ vĩ độ và kinh độ được xác định bằng cách sử dụ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 dưới dạng yêu cầu không hợp lệ.

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ề một phản hồi về Độ cao ở định dạng được chỉ định trong URL yêu cầu.

ElevationResponse

Trường	Bắt buộc	Loại	Mô tả
`results`	bắt buộc	Array<ElevationResult>	Xem ElevationResult để biết thêm thông tin.
`status`	bắt buộc	ElevationStatus	Xem ElevationStatus để biết thêm thông tin.
`error_message`	tùy chọn	chuỗi	Khi dịch vụ trả về một mã trạng thái khác `OK`, có thể có một trường `error_message` bổ sung trong đối tượng phản hồi. 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. Trường này không phải lúc nào cũng được trả về và nội dung của trường có thể thay đổi.

ElevationStatus

Mã trạng thái do dịch vụ trả về.

OK cho biết yêu cầu API đã thành công.
DATA_NOT_AVAILABLE cho biết không có dữ liệu nào cho các vị trí đầu vào.
INVALID_REQUEST cho biết yêu cầu API có định dạng không đúng.
OVER_DAILY_LIMIT cho biết bất kỳ điều nào sau đây:
- Khoá API bị thiếu hoặc không hợp lệ.
- Chức năng thanh toán chưa được bật trên tài khoản của bạn.
- Đã vượt quá mức sử dụng tự áp đặt.
- Phương thức thanh toán được cung cấp không còn hợp lệ (ví dụ: thẻ tín dụng đã hết hạn).
OVER_QUERY_LIMIT cho biết người yêu cầu đã vượt quá hạn mức.
REQUEST_DENIED cho biết API không hoàn tất yêu cầu.
UNKNOWN_ERROR cho biết lỗi không xác định.

Khi mã trạng thái không phải là OK, có thể có một trường error_message bổ sung trong đối tượng phản hồi về Độ 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

Trường	Bắt buộc	Loại	Mô tả
`elevation`	bắt buộc	số	Độ cao của vị trí tính bằng mét.
`location`	bắt buộc	LatLngLiteral	Một phần tử vị trí của vị trí mà dữ liệu độ cao đang được tính toán. Xin lưu ý rằng đối với các yêu cầu về đường dẫn, tập hợp các phần tử vị trí sẽ chứa các điểm được lấy mẫu dọc theo đường dẫn. Xem LatLngLiteral để biết thêm thông tin.
`resolution`	tùy chọn	số	Giá trị cho biết khoảng cách tối đa giữa các điểm dữ liệu mà từ đó độ cao được nội suy, tính bằng mét. Thuộc tính này sẽ bị thiếu nếu không xác định được độ phân giải. Xin lưu ý rằng dữ liệu độ cao trở nên thô hơn (giá trị độ phân giải lớn hơn) khi nhiều điểm được truyền. Để có được giá trị độ cao chính xác nhất cho một điểm, bạn nên truy vấn độc lập.

LatLngLiteral

Một đối tượng mô tả một vị trí cụ thể có Vĩ độ và Kinh độ theo độ thập phân.

Trường	Bắt buộc	Loại	Mô tả
`lat`	bắt buộc	số	Vĩ độ theo độ thập phân
`lng`	bắt buộc	số	Kinh độ theo độ thập phân

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

Ví dụ sau đây yêu cầu độ cao cho Denver, Colorado, "Thành phố cao một dặm":

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, CO và cho Thung lũng Chết, CA).

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

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ừ Núi Whitney, CA đến Badwater, CA, điểm cao nhất và thấp nhất ở lục địa Hoa Kỳ. Chúng tôi yêu cầu 3 samples, để 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>

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

Yêu cầu về độ cao

Các tham số trong yêu cầu

Tất cả yêu cầu

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

Yêu cầu về đường dẫn được lấy mẫu

Chỉ định vị trí

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

Phản hồi về độ cao

Phản hồi về độ cao

ElevationResponse

`results`

`status`

`error_message`

ElevationStatus

ElevationResult

`elevation`

`location`

`resolution`

LatLngLiteral

`lat`

`lng`

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

URL

cURL

JSON

XML

URL

cURL

JSON

XML

URL

cURL

JSON

XML

Yêu cầu và phản hồi về độ cao Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

Yêu cầu về độ cao

Các tham số trong yêu cầu

Tất cả yêu cầu

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

Yêu cầu về đường dẫn được lấy mẫu

Chỉ định vị trí

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

Phản hồi về độ cao

Phản hồi về độ cao

ElevationResponse

results

status

error_message

ElevationStatus

ElevationResult

elevation

location

resolution

LatLngLiteral

lat

lng

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

URL

cURL

JSON

XML

URL

cURL

JSON

XML

URL

cURL

JSON

XML

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

`results`

`status`

`error_message`

`elevation`

`location`

`resolution`

`lat`

`lng`