Yêu cầu độ cao
Các yêu cầu API độ cao đượ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 có thể 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 các vị trí hoặc cá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 API Elevation 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 có độ chính xác cao nhất có thể. Các 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 là nếu các vị trí được trải rộng ra, vì một số hoạt động làm mượt dữ liệu sẽ xảy ra.
Yêu cầu API nâng cao có dạng sau:
https://maps.googleapis.com/maps/api/elevation/outputFormat?parameters
trong đó outputFormat
có thể là một trong những giá trị sau:
json
(nên dùng), cho biết kết quả ở dạng Ký hiệu đối tượng JavaScript (JSON); hoặcxml
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 ở 16384 ký tự đối với tất cả dịch vụ web. Hãy lưu ý đến giới hạn này khi tạo các URL của bạn. 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.
Yêu cầu thông số
Các yêu cầu đến API độ cao sẽ 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 đườ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 các thông số và giá trị có thể có của các thông số đó được biểu thị dưới đây.
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 sẽ lấy một vị trí duy nhất dưới dạng một 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 hình nhiều đường được mã hoá. Có giới hạn 512 điểm cho tham 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 đườ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ó thứ tự xác định một con đường dọc theo bề mặt trái đất. Bạn phải dùng tham số này cùng với tham sốsamples
như mô tả bên dưới. Thông 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 lấy mẫu dọc theo một đường dẫn để trả về dữ liệu độ cao. Tham sốsamples
chiapath
đã cho thành một tập hợp các điểm cách đều theo thứ tự 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 dấu gạch đứ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 Polyline được mã hoá:
locations=enc:gfo}EtohhU
Chuỗi toạ độ vĩ độ và kinh độ được xác định bằng cách sử dụng 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 giá trị bất kỳ trong khoảng từ -90
đến 90
, trong khi kinh độ có thể nhận giá trị bất kỳ trong khoảng từ -180
đến 180
. Nếu bạn chỉ định giá trị vĩ độ hoặc kinh độ không hợp lệ, 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 hình nhiều đường đượ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ạ độ.
Vượt quá 512 điểm hoặc toạ độ trong các thông số "locations" (vị trí) hoặc "path" (đường dẫn) sẽ trả về phản hồi INVALID_REQUEST
.
Chỉ định đường dẫn
Các yêu cầu về đường dẫn 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 cung cấp dữ liệu độ cao dọc theo một đường dẫn theo các khoảng thời gian được chỉ định. Giống như các yêu cầu về vị trí sử dụng tham số locations
, tham số path
sẽ 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 sắp xếp. 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ể sử dụng 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 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 tính đượ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ệ. Các 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 giá trị bất kỳ từ -90
đến 90
, trong khi giá trị kinh độ có thể nhận bất kỳ giá trị nào từ -180
đến 180
. Nếu bạn chỉ định giá trị vĩ độ hoặc kinh độ không hợp lệ, 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 hình nhiều đường đượ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ạ độ. Việc vượt quá 512 điểm hoặc toạ độ trong tham số "vị trí" hoặc "đường dẫn" sẽ trả về phản hồi INVALID_REQUEST
.
Phản hồi khi nâng độ cao
Đối với mỗi yêu cầu hợp lệ, dịch vụ Elevation sẽ trả về một phản hồi Elevation ở định dạng được chỉ định trong URL yêu cầu.
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.
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 phát sinh một mã trạng thái nhất định.
Phản hồi chứa một mảng results
với các phần tử sau:
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. |
Đố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 |
---|---|---|---|
| required | number | Latitude in decimal degrees |
| 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ố cao tầng" ở đị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 câu trả lờ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êu cầu dữ liệu độ cao dọc theo một đường thẳng path
từ Mt. Whitney, CA đến Badwater, CA, điểm cao nhất và thấp nhất ở lục địa Hoa Kỳ. Chúng ta 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>