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

คำขอยกระดับ

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

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

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

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

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

คำขอทั้งหมด

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

คำขอตำแหน่ง

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

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

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

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

สําหรับคําขอที่ถูกต้องแต่ละรายการ บริการ 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>

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

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

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