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

คำขอยกระดับ

ระบบจะสร้างคําขอ 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 อาจมีอาร์กิวเมนต์ต่อไปนี้

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

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

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