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

คำขอยกระดับ

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

ตัวอย่างต่อไปนี้แสดงคำตอบหลายรายการ (สำหรับเดนเวอร์ โคโลราโด และสำหรับ 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'

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

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>