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

คำขอยกระดับ

คำขอ 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 ต้องเข้ารหัสอย่างถูกต้องจึงจะถูกต้องและมีอักขระได้ไม่เกิน 8,192 ตัวสำหรับบริการเว็บทั้งหมด โปรดระวังขีดจำกัดนี้เมื่อสร้าง URL โปรดทราบว่าเบราว์เซอร์ พร็อกซี และเซิร์ฟเวอร์ที่แตกต่างกันอาจมีจำนวนอักขระสูงสุดของ URL แตกต่างกันไปเช่นกัน

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

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

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

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

คำขอทั้งหมด

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

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

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

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

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

การระบุตำแหน่ง

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

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

สตริงพิกัดละติจูดและลองจิจูดจะกำหนดโดยใช้ตัวเลขภายในสตริงข้อความที่คั่นด้วยเครื่องหมายจุลภาค เช่น "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

FieldRequiredTypeDescription
required Array<ElevationResult> See ElevationResult for more information.
requiredElevationStatus See ElevationStatus for more information.
optionalstring

When the service returns a status code other than OK, there may be an additional error_message field within the response object. This field contains more detailed information about thereasons behind the given status code. This field is not always returned, and its content is subject to change.

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

FieldRequiredTypeDescription
requirednumber

The elevation of the location in meters.

requiredLatLngLiteral

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.

optionalnumber

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.

FieldRequiredTypeDescription
requirednumber

Latitude in decimal degrees

requirednumber

Longitude in decimal degrees

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

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