คําขอและคําตอบระดับความสูง

คำขอระดับความสูง

คำขอ Elevation API จะสร้างขึ้นเป็นสตริง URL API จะแสดงข้อมูลระดับความสูงของสถานที่ต่างๆ บนโลก คุณระบุข้อมูลสถานที่ตั้ง ได้ 2 วิธีดังนี้

  • เป็นชุดของ locations อย่างน้อย 1 รายการ
  • เป็นชุดของจุดที่เชื่อมต่อกันตามpath

ทั้ง 2 วิธีนี้ใช้พิกัดละติจูด/ลองจิจูดเพื่อระบุตำแหน่งหรือจุดยอดของเส้นทาง เอกสารนี้อธิบายรูปแบบที่จำเป็นของ URL ของ Elevation API และพารามิเตอร์ที่ใช้ได้

Elevation API จะแสดงข้อมูลสำหรับการค้นหาจุดเดียว ที่มีความแม่นยำสูงสุดเท่าที่จะเป็นไปได้ การค้นหาแบบกลุ่มที่เกี่ยวข้องกับหลายตำแหน่ง อาจแสดงข้อมูลที่มีความแม่นยำน้อยลง โดยเฉพาะอย่างยิ่งหากตำแหน่งอยู่ห่างกัน เนื่องจากมีการปรับข้อมูลให้เรียบ

คำขอ Elevation API มีรูปแบบดังนี้

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

โดย outputFormat อาจมีค่าใดค่าหนึ่งต่อไปนี้

  • json (แนะนำ) ระบุเอาต์พุตใน JavaScript Object Notation (JSON) หรือ
  • xml ระบุเอาต์พุตใน XML ซึ่งอยู่ในโหนด <ElevationResponse>

หมายเหตุ: URL ต้องเข้ารหัสอย่างถูกต้องจึงจะใช้งานได้ และมีความยาวไม่เกิน 16384 ตัวสำหรับเว็บเซอร์วิสทั้งหมด โปรดทราบขีดจำกัดนี้เมื่อสร้าง URL โปรดทราบว่าเบราว์เซอร์ พร็อกซี และเซิร์ฟเวอร์ต่างๆ อาจมีขีดจำกัดอักขระของ URL ที่แตกต่างกันด้วย

ต้องใช้ HTTPS สำหรับคำขอที่ใช้คีย์ API

พารามิเตอร์คำขอ

คำขอไปยัง Elevation API จะใช้พารามิเตอร์ที่แตกต่างกัน โดยขึ้นอยู่กับว่าคำขอเป็นตำแหน่งที่ไม่ต่อเนื่องหรือเส้นทางที่เรียงลำดับ สำหรับตำแหน่งที่แยกกัน คำขอระดับความสูงจะแสดงข้อมูลเกี่ยวกับตำแหน่งที่เฉพาะเจาะจงซึ่งส่งในคำขอ ส่วนสำหรับเส้นทาง คำขอระดับความสูงจะสุ่มตัวอย่างตามเส้นทางที่ระบุแทน

พารามิเตอร์จะคั่นด้วยเครื่องหมายแอมเพอร์แซนด์ (&amp;) ตามมาตรฐานใน URL ทั้งหมด รายการพารามิเตอร์ และค่าที่เป็นไปได้จะระบุไว้ด้านล่าง

คำขอทั้งหมด

  • key -- (ต้องระบุ) คีย์ API ของแอปพลิเคชัน คีย์นี้จะระบุตัวตนแอปพลิเคชันของคุณเพื่อวัตถุประสงค์ในการจัดการโควต้า ดูวิธีรับ คีย์

คำขอตำแหน่ง

  • locations (ต้องระบุ) กำหนดตำแหน่งบนโลกที่จะใช้แสดงผลข้อมูลระดับความสูง พารามิเตอร์นี้ใช้ค่าเป็น ตำแหน่งเดียวในรูปแบบคู่ {ละติจูด,ลองจิจูด} ที่คั่นด้วยคอมมา (เช่น "40.714728,-73.998672") หรือคู่ละติจูด/ลองจิจูดหลายคู่ ที่ส่งเป็นอาร์เรย์หรือเป็น Polyline ที่เข้ารหัส พารามิเตอร์นี้มีขีดจำกัดอยู่ที่ 512 จุด ดูข้อมูลเพิ่มเติมได้ที่ระบุตำแหน่งด้านล่าง

คำขอเส้นทางที่สุ่มตัวอย่าง

  • path (ต้องระบุ) กำหนดเส้นทางบนโลกเพื่อใช้เป็นเส้นทางที่ส่งคืนข้อมูลระดับความสูง พารามิเตอร์นี้กำหนดชุดคู่ {ละติจูด,ลองจิจูด} ที่เรียงลำดับแล้ว 2 คู่ขึ้นไป ซึ่งกำหนดเส้นทางตามพื้นผิวโลก พารามิเตอร์นี้ต้องใช้ร่วมกับsamples พารามิเตอร์ที่อธิบายไว้ด้านล่าง พารามิเตอร์นี้มีจุดได้สูงสุด 512 จุด ดูข้อมูลเพิ่มเติมได้ที่ระบุเส้นทางด้านล่าง
  • samples (ต้องระบุ) ระบุจำนวนจุดตัวอย่าง ตามเส้นทางที่จะแสดงข้อมูลระดับความสูง พารามิเตอร์ samples จะแบ่ง path ที่ระบุ ออกเป็นชุดจุดที่เรียงตามลำดับซึ่งมีระยะห่างเท่ากันตามเส้นทาง

ระบุสถานที่

คำขอตำแหน่งจะระบุผ่านการใช้พารามิเตอร์ locations ซึ่งระบุคำขอระดับความสูง สำหรับตำแหน่งที่เฉพาะเจาะจงที่ส่งเป็น ค่าละติจูด/ลองจิจูด

พารามิเตอร์ locations อาจมีอาร์กิวเมนต์ต่อไปนี้

  • พิกัดเดียว: locations=40.714728,-73.998672
  • อาร์เรย์ของพิกัดที่คั่นด้วยอักขระไปป์ ('|') locations=40.714728,-73.998672|-34.397,150.644
  • ชุดพิกัดที่เข้ารหัสโดยใช้อัลกอริทึม Polyline ที่เข้ารหัส: locations=enc:gfo}EtohhU

สตริงพิกัดละติจูดและลองจิจูดกำหนดโดยใช้ตัวเลข ภายในสตริงข้อความที่คั่นด้วยคอมมา เช่น "40.714728,-73.998672" เป็นค่า locations ที่ถูกต้อง ค่าละติจูดและ ลองจิจูดต้องสอดคล้องกับตำแหน่งที่ถูกต้อง บนพื้นผิวโลก ค่าละติจูดเป็นค่าใดก็ได้ระหว่าง -90 ถึง 90 ส่วนค่าลองจิจูดเป็นค่าใดก็ได้ระหว่าง -180 ถึง 180 หากคุณระบุค่าละติจูดหรือลองจิจูดที่ไม่ถูกต้อง คำขอจะถูกปฏิเสธ เนื่องจากเป็นคำขอที่ไม่ถูกต้อง

คุณส่งพิกัดได้สูงสุด 512 รายการภายในอาร์เรย์หรือโพลีไลน์ที่เข้ารหัส ขณะที่ ยังคงสร้าง URL ที่ถูกต้อง โปรดทราบว่าเมื่อส่งพิกัดหลายรายการ ความแม่นยำของข้อมูลที่ส่งกลับอาจมีความละเอียดต่ำกว่าเมื่อขอข้อมูลสำหรับพิกัดเดียว การระบุจุดหรือพิกัดเกิน 512 จุดในพารามิเตอร์ "locations" หรือ "path" จะทำให้ระบบแสดงการตอบกลับ INVALID_REQUEST

ระบุเส้นทาง

คำขอเส้นทางที่สุ่มตัวอย่างจะระบุผ่านการใช้พารามิเตอร์ path และ samples ซึ่งระบุคำขอข้อมูลระดับความสูง ตามเส้นทางในช่วงเวลาที่ระบุ เช่นเดียวกับคำขอตามตำแหน่งที่ใช้พารามิเตอร์ locations พารามิเตอร์ path จะระบุ ชุดค่าละติจูดและลองจิจูด อย่างไรก็ตาม path จะระบุชุดจุดยอดที่เรียงลำดับ ซึ่งแตกต่างจากคำขอตำแหน่ง ระบบจะสุ่มตัวอย่างคำขอเส้นทางตาม ความยาวของเส้นทางโดยอิงตามจำนวนsamples ที่ระบุ (รวมจุดสิ้นสุด) แทนที่จะแสดงข้อมูลความสูงเฉพาะที่จุดยอด

path พารามิเตอร์อาจใช้อาร์กิวเมนต์ใดอาร์กิวเมนต์หนึ่งต่อไปนี้

  • อาร์เรย์ของสตริงข้อความพิกัดที่คั่นด้วยคอมมาอย่างน้อย 2 รายการซึ่งคั่น โดยใช้อักขระไปป์ ("|") ดังนี้ path=40.714728,-73.998672|-34.397,150.644
  • พิกัดที่เข้ารหัสโดยใช้อัลกอริทึม Polyline ที่เข้ารหัส path=enc:gfo}EtohhUxD@bAxJmGF

สตริงพิกัดละติจูดและลองจิจูดจะกำหนดโดยใช้ตัวเลขภายในสตริงข้อความที่คั่นด้วยคอมมา เช่น "40.714728,-73.998672|-34.397, 150.644" เป็นค่า path ที่ถูกต้อง ค่าละติจูดและลองจิจูดต้องสอดคล้องกับตำแหน่งที่ถูกต้องบนพื้นผิวโลก ค่าละติจูดอาจเป็นค่าใดก็ได้ ระหว่าง -90 ถึง 90 ส่วนค่าลองจิจูดอาจเป็นค่าใดก็ได้ระหว่าง -180 ถึง 180 หากคุณระบุค่าละติจูดหรือลองจิจูดที่ไม่ถูกต้อง ระบบจะปฏิเสธคำขอของคุณเนื่องจากเป็นคำขอที่ไม่ถูกต้อง

คุณส่งพิกัดได้สูงสุด 512 รายการภายในอาร์เรย์หรือโพลีไลน์ที่เข้ารหัส ขณะที่ ยังคงสร้าง URL ที่ถูกต้อง โปรดทราบว่าเมื่อส่งพิกัดหลายรายการ ความแม่นยำของข้อมูลที่ส่งกลับอาจมีความละเอียดต่ำกว่าเมื่อขอข้อมูลสำหรับพิกัดเดียว การระบุจุดหรือพิกัดเกิน 512 จุดในพารามิเตอร์ "locations" หรือ "path" จะทำให้ระบบแสดงการตอบกลับ INVALID_REQUEST

คำตอบเกี่ยวกับระดับความสูง

  • อาร์เรย์ของสตริงข้อความพิกัดที่คั่นด้วยคอมมาอย่างน้อย 2 รายการซึ่งคั่น โดยใช้อักขระไปป์ ("|") ดังนี้ path=40.714728,-73.998672|-34.397,150.644
  • พิกัดที่เข้ารหัสโดยใช้อัลกอริทึม Polyline ที่เข้ารหัส path=enc:gfo}EtohhUxD@bAxJmGF

สตริงพิกัดละติจูดและลองจิจูดจะกำหนดโดยใช้ตัวเลขภายในสตริงข้อความที่คั่นด้วยคอมมา เช่น "40.714728,-73.998672|-34.397, 150.644" เป็นค่า path ที่ถูกต้อง ค่าละติจูดและลองจิจูดต้องสอดคล้องกับตำแหน่งที่ถูกต้องบนพื้นผิวโลก ค่าละติจูดอาจเป็นค่าใดก็ได้ ระหว่าง -90 ถึง 90 ส่วนค่าลองจิจูดอาจเป็นค่าใดก็ได้ระหว่าง -180 ถึง -180 หากคุณระบุค่าละติจูดหรือลองจิจูดที่ไม่ถูกต้อง ระบบจะปฏิเสธคำขอของคุณเนื่องจากเป็นคำขอที่ไม่ถูกต้อง

คุณส่งพิกัดได้สูงสุด 512 รายการภายในอาร์เรย์หรือโพลีไลน์ที่เข้ารหัส ขณะที่ ยังคงสร้าง URL ที่ถูกต้อง โปรดทราบว่าเมื่อส่งพิกัดหลายรายการ ความแม่นยำของข้อมูลที่ส่งกลับอาจมีความละเอียดต่ำกว่าเมื่อขอข้อมูลสำหรับพิกัดเดียว การระบุจุดหรือพิกัดเกิน 512 จุดในพารามิเตอร์ "locations" หรือ "path" จะทำให้ระบบแสดงการตอบกลับ INVALID_REQUEST

คำตอบเกี่ยวกับระดับความสูง

สำหรับคำขอที่ถูกต้องแต่ละรายการ บริการระดับความสูงจะแสดงผลการตอบกลับระดับความสูง ในรูปแบบที่ระบุไว้ใน URL ของคำขอ

ElevationResponse

ช่อง ต้องระบุ ประเภท คำอธิบาย
ต้องระบุ Array<ElevationResult> ดูข้อมูลเพิ่มเติมได้ที่ ElevationResult
ต้องระบุ ElevationStatus ดูข้อมูลเพิ่มเติมได้ที่ ElevationStatus
ไม่บังคับ สตริง

เมื่อบริการแสดงรหัสสถานะอื่นที่ไม่ใช่ OK อาจมีฟิลด์ error_message เพิ่มเติมภายใน ออบเจ็กต์การตอบกลับ ฟิลด์นี้มีข้อมูลโดยละเอียดเพิ่มเติม เกี่ยวกับสาเหตุที่อยู่เบื้องหลังรหัสสถานะที่ระบุ ระบบอาจไม่แสดงช่องนี้เสมอไป และเนื้อหาของช่องอาจมีการเปลี่ยนแปลง

ElevationStatus

รหัสสถานะที่บริการส่งกลับ

  • OK ซึ่งหมายความว่าคำขอ API สำเร็จ
  • DATA_NOT_AVAILABLE ซึ่งระบุว่าไม่มีข้อมูลสำหรับสถานที่ตั้งที่ป้อน
  • INVALID_REQUEST ซึ่งบ่งชี้ว่าคำขอ API มีรูปแบบไม่ถูกต้อง
  • OVER_DAILY_LIMIT ที่ระบุข้อมูลต่อไปนี้
    • คีย์ API ขาดหายไปหรือไม่ถูกต้อง
    • บัญชีของคุณไม่ได้เปิดใช้การเรียกเก็บเงิน
    • มีการใช้งานเกินขีดจำกัดการใช้งานที่กำหนดเอง
    • วิธีการชำระเงินที่ระบุใช้ไม่ได้อีกต่อไป (เช่น บัตรเครดิตหมดอายุ)
  • OVER_QUERY_LIMIT แสดงว่าผู้ขอใช้โควต้าเกินแล้ว
  • REQUEST_DENIED ซึ่งบ่งบอกว่า API ไม่ได้ดำเนินการตามคำขอให้เสร็จสมบูรณ์
  • UNKNOWN_ERROR แสดงว่าเกิดข้อผิดพลาดที่ไม่รู้จัก

เมื่อรหัสสถานะเป็นอย่างอื่นที่ไม่ใช่ OK อาจมีฟิลด์ error_message เพิ่มเติมภายในออบเจ็กต์การตอบกลับระดับความสูง ฟิลด์นี้มี ข้อมูลโดยละเอียดเพิ่มเติมเกี่ยวกับเหตุผลที่อยู่เบื้องหลังรหัสสถานะที่ระบุ

การตอบกลับจะมีอาร์เรย์ results ที่มีองค์ประกอบต่อไปนี้

ElevationResult

ช่อง ต้องระบุ ประเภท คำอธิบาย
ต้องระบุ ตัวเลข

ระดับความสูงของสถานที่ตั้งเป็นเมตร
ต้องระบุ LatLngLiteral

องค์ประกอบตำแหน่งของตำแหน่งที่กำลังคำนวณข้อมูลระดับความสูง โปรดทราบว่าสำหรับคำขอเส้นทาง ชุดองค์ประกอบตำแหน่ง จะมีจุดที่สุ่มตามเส้นทาง

ดูข้อมูลเพิ่มเติมได้ที่ LatLngLiteral

ไม่บังคับ ตัวเลข

ค่าที่ระบุระยะทางสูงสุดระหว่างจุดข้อมูลจาก ที่ประมาณค่าความสูงเป็นเมตร พร็อพเพอร์ตี้นี้จะ หายไปหากไม่ทราบความละเอียด โปรดทราบว่าข้อมูลระดับความสูง จะหยาบขึ้น (ค่าความละเอียดมากขึ้น) เมื่อส่งจุดหลายจุด หากต้องการรับค่าระดับความสูงที่แม่นยำที่สุดสำหรับจุดหนึ่งๆ คุณควรค้นหาค่าดังกล่าวแยกกัน

LatLngLiteral

ออบเจ็กต์ที่อธิบายสถานที่ตั้งที่เฉพาะเจาะจงโดยมีละติจูดและลองจิจูดใน องศาทศนิยม

ช่อง ต้องระบุ ประเภท คำอธิบาย
ต้องระบุ ตัวเลข

ละติจูดในหน่วยองศาทศนิยม
ต้องระบุ ตัวเลข

ลองจิจูดในหน่วยองศาทศนิยม

ตัวอย่างระดับความสูงเชิงตำแหน่ง

ตัวอย่างต่อไปนี้จะขอระดับความสูงของเดนเวอร์ รัฐโคโลราโด ซึ่งเป็น "เมืองที่อยู่สูงจากระดับน้ำทะเล 1 ไมล์"

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>

ตัวอย่างต่อไปนี้แสดงการตอบกลับหลายรายการ (สำหรับเดนเวอร์ รัฐโคโลราโด และสำหรับ เดธวัลเลย์ รัฐแคลิฟอร์เนีย)

คำขอนี้แสดงการใช้แฟล็ก 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'

คำขอนี้แสดงการใช้แฟล็ก output XML ดังนี้

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 จากภูเขา Whitney ในแคลิฟอร์เนียไปยัง Badwater ในแคลิฟอร์เนีย ซึ่งเป็นจุดที่สูงที่สุดและ ต่ำที่สุดในสหรัฐอเมริกาภาคพื้นทวีป เราขอ 3 samples ซึ่งจะรวมถึงจุดสิ้นสุด 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>