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

คำขอยกระดับ

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

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

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

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

คำขอทั้งหมด

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

คำขอตำแหน่ง

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

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

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

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

สําหรับคําขอที่ถูกต้องแต่ละรายการ บริการ Elevation จะแสดงการตอบกลับ Elevation ในรูปแบบที่ระบุไว้ใน 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 เพิ่มเติมภายในออบเจ็กต์การตอบกลับของ Elevation ช่องนี้มี ข้อมูลโดยละเอียดเกี่ยวกับเหตุผลเบื้องหลังรหัสสถานะที่ระบุ

การตอบกลับมีอาร์เรย์ 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

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

ตัวอย่างต่อไปนี้ขอระดับความสูงของเดนเวอร์ รัฐโคโลราโด "เมืองที่สูง 1,600 เมตร" ในรูปแบบ 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>

ตัวอย่างต่อไปนี้แสดงคำตอบหลายรายการ (สำหรับเดนเวอร์ โคโลราโด และสำหรับ Death Valley, CA)

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

คำขอนี้แสดงการใช้ Flag 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, แคลิฟอร์เนีย สูงสุดและ จุดต่ำสุดในทวีปอเมริกาเหนือ เราขอ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>