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

คำขอการยกระดับ

คำขอ 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 ที่แตกต่างกันด้วย

คำขอที่ใช้คีย์ API ต้องใช้ HTTPS

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

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

พารามิเตอร์จะแยกกันโดยใช้อักขระแอมเพอร์แซนด์ (&) ตามมาตรฐานใน URL ทั้งหมด รายการพารามิเตอร์และค่าที่เป็นไปได้จะแสดงอยู่ด้านล่าง

คำขอทั้งหมด

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

คำขอตามตำแหน่ง

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

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

• path (ต้องระบุ) กำหนดเส้นทางบนโลกที่จะแสดงผลข้อมูลระดับความสูง พารามิเตอร์นี้กำหนดชุดคู่ {ละติจูด,ลองจิจูด} ที่เรียงลำดับตั้งแต่ 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 จุดในพารามิเตอร์ "locations" หรือ "path" จะแสดงการตอบกลับ 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 จุดในพารามิเตอร์ "locations" หรือ "path" จะแสดงการตอบกลับ INVALID_REQUEST

การตอบสนองต่อการยกระดับ

• อาร์เรย์ของสตริงข้อความพิกัดที่คั่นด้วยคอมมาอย่างน้อย 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 จุดในพารามิเตอร์ "locations" หรือ "path" จะแสดงการตอบกลับ INVALID_REQUEST

การตอบสนองต่อการยกระดับ

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

ElevationResponse

ช่อง	ต้องระบุ	ประเภท	คำอธิบาย
results	ต้องระบุ	Array<ElevationResult>	ดูข้อมูลเพิ่มเติมได้ที่ ElevationResult
status	ต้องระบุ	ElevationStatus	ดูข้อมูลเพิ่มเติมได้ที่ ElevationStatus
error_message	ไม่บังคับ	สตริง	เมื่อบริการแสดงรหัสสถานะอื่นที่ไม่ใช่ OK อาจมีช่อง error_message เพิ่มเติมภายในออบเจ็กต์การตอบกลับ ช่องนี้มีข้อมูลโดยละเอียดเพิ่มเติมเกี่ยวกับสาเหตุที่อยู่เบื้องหลังรหัสสถานะที่ระบุ ระบบไม่ได้แสดงผลช่องนี้เสมอไป และเนื้อหาอาจมีการเปลี่ยนแปลง

ElevationStatus

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

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

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

หมายเหตุ: เราไม่รับประกันว่าช่องนี้จะแสดงอยู่เสมอ และเนื้อหาในช่องอาจมีการเปลี่ยนแปลง

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

ElevationResult

ช่อง	ต้องระบุ	ประเภท	คำอธิบาย
elevation	ต้องระบุ	ตัวเลข	ระดับความสูงของสถานที่ในหน่วยเมตร
location	ต้องระบุ	LatLngLiteral	องค์ประกอบตำแหน่งของตำแหน่งที่กำลังคำนวณข้อมูลระดับความสูง โปรดทราบว่าสำหรับคำขอเส้นทาง ชุดองค์ประกอบตำแหน่งจะมีจุดตัวอย่างตามเส้นทาง ดูข้อมูลเพิ่มเติมได้ที่ LatLngLiteral
resolution	ไม่บังคับ	ตัวเลข	ค่าที่ระบุระยะทางสูงสุดระหว่างจุดข้อมูลที่ใช้ประมาณค่าระดับความสูงในหน่วยเมตร พร็อพเพอร์ตี้นี้จะหายไปหากไม่ทราบความละเอียด โปรดทราบว่าข้อมูลระดับความสูงจะมีความละเอียดน้อยลง (ค่าความละเอียดสูงขึ้น) เมื่อมีการส่งผ่านจุดหลายจุด หากต้องการรับค่าระดับความสูงที่แม่นยำที่สุดสำหรับจุดหนึ่งๆ คุณควรค้นหาจุดนั้นแยกต่างหาก

LatLngLiteral

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

ช่อง	ต้องระบุ	ประเภท	คำอธิบาย
lat	ต้องระบุ	ตัวเลข	ละติจูดในหน่วยองศาทศนิยม
lng	ต้องระบุ	ตัวเลข	ลองจิจูดในหน่วยองศาทศนิยม

ตัวอย่างการยกระดับตามตำแหน่ง

ตัวอย่างต่อไปนี้จะขอระดับความสูงของเดนเวอร์ โคโลราโด ซึ่งเป็น "เมืองที่สูงจากระดับน้ำทะเล 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>
        
        

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

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