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

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

คำขอ Elevation API จะสร้างขึ้นเป็นสตริง URL โดย API จะแสดงข้อมูลระดับความสูงของสถานที่ต่างๆ บนโลก คุณระบุข้อมูลสถานที่ได้ 1 ใน 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
• พิกัดที่เข้ารหัสโดยใช้ Encoded Polyline Algorithm: 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
• พิกัดที่เข้ารหัสโดยใช้ Encoded Polyline Algorithm: 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

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

LatLngLiteral

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

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

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

https://maps.googleapis.com/maps/api/elevation/json
    ?locations=39.7391536%2C-104.9847034
    &key=YOUR_API_KEY
      

curl -L -X GET 'https://maps.googleapis.com/maps/api/elevation/json?locations=39.7391536%2C-104.9847034&key=YOUR_API_KEY'
      

        
{
  "results":
    [
      {
        "elevation": 1608.637939453125,
        "location": { "lat": 39.7391536, "lng": -104.9847034 },
        "resolution": 4.771975994110107,
      },
    ],
  "status": "OK",
}
        
        

        
<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

https://maps.googleapis.com/maps/api/elevation/json
    ?locations=39.7391536%2C-104.9847034%7C36.455556%2C-116.866667
    &key=YOUR_API_KEY
      

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

      
{
  "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",
}
      
      

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

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 -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'
    

      
{
  "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",
}
      
      

      
<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>