คำขอยกระดับ
คำขอ Heightion API จะสร้างขึ้นเป็นสตริง URL API จะแสดงผลข้อมูลระดับความสูงของตำแหน่งบนโลก คุณระบุข้อมูลตำแหน่งได้ ด้วยวิธีใดวิธีหนึ่งต่อไปนี้
- ชุด
locations
อย่างน้อย 1 รายการ - เป็นชุดของจุดเชื่อมต่อตลอด
path
ทั้ง 2 วิธีนี้จะใช้พิกัดละติจูด/ลองจิจูดเพื่อระบุตำแหน่งหรือจุดยอดมุมของเส้นทาง เอกสารนี้อธิบายรูปแบบที่จำเป็นของ URL ของ Elevation API และพารามิเตอร์ที่ใช้ได้
Heightion API จะแสดงข้อมูลของการค้นหาแบบจุดเดียวที่มีความแม่นยำสูงสุดเท่าที่จะเป็นไปได้ การค้นหาแบบกลุ่มที่เกี่ยวข้องกับสถานที่หลายแห่งอาจแสดงผลข้อมูลที่มีความแม่นยำน้อยกว่า โดยเฉพาะอย่างยิ่งหากตำแหน่งเหล่านั้นอยู่ห่างกัน ในขณะที่บางจุดทำให้ข้อมูลเรียบเนียน
คำขอ elevion API จะใช้รูปแบบต่อไปนี้
https://maps.googleapis.com/maps/api/elevation/outputFormat?parameters
โดยที่ outputFormat
อาจเป็นค่าใดค่าหนึ่งต่อไปนี้
json
(แนะนำ) ระบุเอาต์พุตใน JavaScript Object Notation (JSON) หรือxml
ระบุเอาต์พุตใน XML ซึ่งรวมอยู่ในโหนด<ElevationResponse>
หมายเหตุ: URL ต้องเข้ารหัสอย่างถูกต้องเพื่อให้ใช้งานได้และต้องมีอักขระไม่เกิน 16,384 ตัวสำหรับบริการเว็บทั้งหมด โปรดระวังขีดจำกัดนี้เมื่อสร้าง URL โปรดทราบว่าเบราว์เซอร์ พร็อกซี และเซิร์ฟเวอร์ที่แตกต่างกันอาจมีจำนวนอักขระสูงสุดสำหรับ URL ที่ต่างกันได้เช่นเดียวกัน
ต้องใช้ HTTPS สำหรับคำขอที่ใช้คีย์ API
พารามิเตอร์คําขอ
คำขอที่ส่งไปยัง elevion API ใช้พารามิเตอร์ที่ต่างกัน โดยพิจารณาว่าคำขอมีไว้สำหรับสถานที่ตั้งที่แยกขาดหรือสำหรับเส้นทางที่เรียงลำดับ สำหรับสถานที่ตั้งที่แยกกัน คำขอข้อมูลผลตอบแทนการยกระดับสำหรับตำแหน่งที่เฉพาะเจาะจงที่ส่งผ่านในคำขอ สำหรับเส้นทาง ระบบจะสุ่มตัวอย่างคำขอยกระดับตามเส้นทางที่ระบุแทน
เช่นเดียวกับมาตรฐานใน URL ทั้งหมด ระบบจะคั่นพารามิเตอร์โดยใช้อักขระแอมเพอร์แซนด์ (&
) รายการพารามิเตอร์และค่าที่เป็นไปได้แสดงไว้ด้านล่างนี้
คำขอทั้งหมด
key
— (จำเป็น) คีย์ API ของแอปพลิเคชันของคุณ คีย์นี้จะระบุแอปพลิเคชันของคุณเพื่อวัตถุประสงค์ด้านการจัดการโควต้า ดูวิธีรับคีย์
คำขอตามตำแหน่ง
locations
(ต้องระบุ) ระบุตำแหน่งบนพื้นโลกที่จะแสดงผลข้อมูลระดับความสูง พารามิเตอร์นี้จะใช้ตำแหน่งเดียวเป็นคู่ {latitude,longitude} ที่คั่นด้วยคอมมา (เช่น "40.714728,-73.998672") หรือคู่ละติจูด/ลองจิจูดหลายคู่ที่ส่งผ่านเป็นอาร์เรย์หรือเป็นเส้นคู่ที่เข้ารหัส พารามิเตอร์นี้จำกัดคะแนนอยู่ที่ 512 คะแนน สำหรับข้อมูลเพิ่มเติม โปรดดูการระบุตำแหน่งด้านล่าง
คำขอเส้นทางตัวอย่าง
path
(ต้องระบุ) กำหนดเส้นทางบนพื้นโลกที่จะแสดงข้อมูลระดับความสูง พารามิเตอร์นี้กำหนดชุดคู่ {latitude,longitude} ที่มีลำดับตั้งแต่ 2 คู่ขึ้นไปเพื่อกำหนดเส้นทางตามพื้นผิวของโลก พารามิเตอร์นี้ต้องใช้ร่วมกับพารามิเตอร์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
ที่ถูกต้อง ค่าละติจูดและลองจิจูดต้องตรงกับตำแหน่งที่ถูกต้องบนพื้นโลก ละติจูดมีค่าระหว่าง -90
ถึง 90
ได้ ส่วนค่าลองจิจูดจะมีค่าระหว่าง -180
ถึง 180
หากคุณระบุค่าละติจูดหรือลองจิจูดไม่ถูกต้อง คำขอจะถูกปฏิเสธโดยถือว่าเป็นคำขอที่ไม่ถูกต้อง
คุณอาจส่งผ่านพิกัดได้สูงสุด 512 พิกัดภายในอาร์เรย์หรือเส้นประกอบที่เข้ารหัส โดยที่ยังคงสร้าง URL ที่ถูกต้องอยู่
โปรดทราบว่าเมื่อส่งผ่านหลายพิกัด ความถูกต้องของข้อมูลที่ส่งคืนอาจต่ำกว่าความละเอียดที่ใช้ในการขอข้อมูลสำหรับพิกัดเดียว
เมื่อมีจุดหรือพิกัดเกิน 512 จุดในพารามิเตอร์ "ตำแหน่ง" หรือ "เส้นทาง" จะแสดงผลการตอบสนอง INVALID_REQUEST
การระบุเส้นทาง
คำขอเส้นทางตัวอย่างจะระบุผ่านการใช้พารามิเตอร์ path
และ samples
ซึ่งระบุคำขอสำหรับข้อมูลระดับความสูงพร้อมเส้นทางในช่วงเวลาที่กำหนด เช่นเดียวกับคำขอตำแหน่งที่ใช้พารามิเตอร์ 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
ที่ถูกต้อง ค่าละติจูดและลองจิจูดต้องตรงกับ
ตำแหน่งที่ถูกต้องบนพื้นโลก ละติจูดมีค่าระหว่าง -90
ถึง 90
ได้ ส่วนค่าลองจิจูดจะมีค่าระหว่าง -180
ถึง 180
หากคุณระบุค่าละติจูดหรือลองจิจูดไม่ถูกต้อง คำขอจะถูกปฏิเสธโดยถือว่าเป็นคำขอที่ไม่ถูกต้อง
คุณอาจส่งผ่านพิกัดได้สูงสุด 512 พิกัดภายในอาร์เรย์หรือเส้นประกอบที่เข้ารหัส โดยที่ยังคงสร้าง URL ที่ถูกต้องอยู่ โปรดทราบว่าเมื่อส่งผ่านหลายพิกัด ความถูกต้องของข้อมูลที่ส่งคืนอาจต่ำกว่าความละเอียดที่ใช้ในการขอข้อมูลสำหรับพิกัดเดียว เมื่อมีจุดหรือพิกัดเกิน 512 จุดในพารามิเตอร์ "ตำแหน่ง" หรือ "เส้นทาง" จะแสดงผลการตอบสนอง INVALID_REQUEST
การตอบกลับระดับความสูง
สำหรับคำขอที่ถูกต้องแต่ละรายการ บริการระดับความสูงจะส่งคำตอบการยกระดับกลับมาในรูปแบบที่ระบุภายใน URL ของคำขอ
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.
เมื่อรหัสสถานะไม่ใช่ OK
อาจมีช่อง error_message
เพิ่มเติมภายในออบเจ็กต์การตอบกลับระดับความสูง ช่องนี้มีข้อมูลที่ละเอียดขึ้นเกี่ยวกับเหตุผลเบื้องหลังรหัสสถานะที่ระบุ
คำตอบประกอบด้วยอาร์เรย์ results
ที่มีองค์ประกอบต่อไปนี้
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. |
ออบเจ็กต์ location
มีองค์ประกอบต่อไปนี้
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 |
ตัวอย่างระดับความสูงตามตำแหน่ง
ตัวอย่างต่อไปนี้ขอระดับความสูงสำหรับ "เดนเวอร์ โคโลราโด" "Mile High City" ในรูปแบบ 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
จากภูเขาวิทนีย์ แคลิฟอร์เนีย ไปยัง Badwater, แคลิฟอร์เนีย ซึ่งเป็นจุดสูงสุดและต่ำสุดในทวีปของสหรัฐอเมริกา เราจะขอให้มี samples
3 จุด ซึ่งจะรวมปลายทาง 2 จุดและจุดครึ่งหนึ่ง
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>