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

คำขอยกระดับ

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

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

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

Heightion API จะแสดงข้อมูลของการค้นหาแบบจุดเดียวที่มีความแม่นยำสูงสุดเท่าที่จะเป็นไปได้ การค้นหาแบบกลุ่มที่เกี่ยวข้องกับสถานที่หลายแห่งอาจแสดงผลข้อมูลที่มีความแม่นยำน้อยกว่า โดยเฉพาะอย่างยิ่งหากตำแหน่งเหล่านั้นอยู่ห่างกัน ในขณะที่บางจุดทำให้ข้อมูลเรียบเนียน

คำขอ elevion API จะใช้รูปแบบต่อไปนี้

https://maps.googleapis.com/maps/api/elevation/outputFormat?parameters

โดยที่ outputFormat อาจเป็นค่าใดค่าหนึ่งต่อไปนี้

  • json (แนะนำ) ระบุเอาต์พุตใน JavaScript Object Notation (JSON) หรือ
  • xml ระบุเอาต์พุตใน XML ซึ่งรวมอยู่ในโหนด <ElevationResponse>

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

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

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

คำขอที่ส่งไปยัง elevion 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 จุดในพารามิเตอร์ "ตำแหน่ง" หรือ "เส้นทาง" จะแสดงผลการตอบสนอง INVALID_REQUEST

การระบุเส้นทาง

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

พารามิเตอร์ path อาจใช้อาร์กิวเมนต์ใดก็ได้ต่อไปนี้

  • อาร์เรย์ของสตริงข้อความพิกัดที่คั่นด้วยคอมมาอย่างน้อย 2 รายการซึ่งคั่นด้วยอักขระไปป์ ("|"): path=40.714728,-73.998672|-34.397,150.644
  • พิกัดที่เข้ารหัสโดยใช้ อัลกอริทึมโพลีไลน์ที่เข้ารหัส: 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

ตัวอย่างระดับความสูงตามตำแหน่ง

ตัวอย่างต่อไปนี้ขอระดับความสูงสำหรับ "เดนเวอร์ โคโลราโด" "Mile High City" ในรูปแบบ 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 จากภูเขาวิทนีย์ แคลิฟอร์เนีย ไปยัง 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>