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

คำขอระดับความสูง

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

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

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

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

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

คำขอทั้งหมด

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

คำขอตำแหน่ง

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

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

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

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

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

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

  • พิกัดเดียว: locations=40.714728,-73.998672
  • อาร์เรย์ของพิกัดที่คั่นด้วยอักขระไปป์ ('|') locations=40.714728,-73.998672|-34.397,150.644
  • ชุดพิกัดที่เข้ารหัสโดยใช้ อัลกอริทึม Encoded 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
  • พิกัดที่เข้ารหัสโดยใช้ อัลกอริทึม Encoded 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 เพิ่มเติมภายในออบเจ็กต์การตอบกลับระดับความสูง ฟิลด์นี้มีข้อมูลเพิ่มเติม โดยละเอียดเกี่ยวกับสาเหตุที่อยู่เบื้องหลังรหัสสถานะที่ระบุ

การตอบกลับจะมีอาร์เรย์ 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 ไมล์" ในรูปแบบ 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>

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

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

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