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

คำขอยกระดับ

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

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

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

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

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

คำขอทั้งหมด

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