高度リクエスト
Elevation API リクエストは、URL 文字列として構成されます。この API は、地球上の各地点の高度データを返します。位置情報は、次の 2 つの方法のいずれかで指定します。
- 1 つ以上の
locations
のセットとして。 path
に沿った一連の連結点。
どちらの方法でも、緯度と経度の座標を使用して場所やパスの頂点を指定します。このドキュメントでは、Elevation API の URL の必須形式と使用可能なパラメータについて説明します。
Elevation API は、単一地点のクエリに対して可能な限り高い精度のデータを返します。複数の場所が関係するバッチクエリでは、特に複数の場所が分散している場合はデータが平滑化されるため、精度の低いデータが返される可能性があります。
Elevation API リクエストの形式は次のとおりです。
https://maps.googleapis.com/maps/api/elevation/outputFormat?parameters
ここで、outputFormat
には次のいずれかの値を指定できます。
json
(推奨)は、出力が JavaScript Object Notation(JSON)であることを示します。xml
は、<ElevationResponse>
ノード内にラップされた XML での出力を示します。
注: URL は、有効なように適切にエンコードされ、すべてのウェブサービスで 16,384 文字以内である必要があります。URL を作成する際は、この制限に注意してください。また、URL の文字数制限は、ブラウザ、プロキシ、サーバーによって異なる場合があります。
API キーを使用するリクエストには HTTPS が必要です。
リクエスト パラメータ
Elevation API へのリクエストでは、個別の場所に対するリクエストか、順序付けられたパスに対するリクエストかによって、異なるパラメータが使用されます。個別の場所の場合、高度をリクエストすると、リクエストで渡された特定の場所のデータが返されます。パスの場合は、指定されたパスに沿ってサンプリングされます。
すべての URL の標準と同様に、パラメータはアンパサンド(&
)文字を使用して区切ります。パラメータと有効な値のリストを以下に示します。
すべてのリクエスト
key
- (必須)アプリの API キー。このキーでアプリケーションを識別し、割り当てを管理します。キーの取得方法を確認する。
位置リクエスト
locations
(必須)は、高度データを返す地球上の場所を定義します。このパラメータは、単一の位置をカンマで区切った {緯度,経度} のペア(例: 「40.714728,-73.998672」)、または複数の緯度と経度のペアとして配列またはエンコードされたポリラインとして渡します。このパラメータには 512 ポイントという上限があります。詳細については、後述のロケーションの指定をご覧ください。
サンプリングされたパスリクエスト
path
(必須)は、高度データを返す地球上のパスを定義します。このパラメータは、地表面に沿ったパスを定義する 2 つ以上の {latitude,longitude} のペアのセットを定義します。このパラメータは、以下で説明するsamples
パラメータと組み合わせて使用する必要があります。この特定のパラメータには 512 ポイントの上限があります。詳細については、後述のパスの指定をご覧ください。samples
(必須)は、高度データを返すパス上のサンプル ポイントの数を指定します。samples
パラメータで、指定されたpath
がパスに沿って等間隔に並んだ一連のポイントに分割されます。
ロケーションの指定
位置リクエストは、locations
パラメータを使用して指定します。このパラメータは、緯度と経度の値として渡される特定の場所の高度リクエストを示します。
locations
パラメータは次の引数を取ります。
- 単一の座標:
locations=40.714728,-73.998672
- パイプ文字(「
|
」)で区切られた座標の配列:locations=40.714728,-73.998672|-34.397,150.644
- エンコード ポリライン アルゴリズムを使用してエンコードされた座標のセット:
locations=enc:gfo}EtohhU
緯度と経度の座標文字列は、カンマ区切りのテキスト文字列内の数字を使用して定義されます。たとえば、「40.714728,-73.998672」は有効な locations
値です。緯度と経度の値は、地表の有効な位置に対応している必要があります。緯度の値は -90
~90
の任意の値、経度の値は -180
~180
の任意の値を指定できます。無効な緯度と経度の値を指定すると、リクエストは不正なリクエストとして拒否されます。
有効な URL を作成したまま、配列またはエンコードされたポリライン内で最大 512 個の座標を渡すことができます。複数の座標を渡すと、単一の座標のデータをリクエストする場合よりも、返されるデータの精度が低下することがあります。locations または path パラメータでポイントまたは座標が 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
の任意の値を指定できます。無効な緯度と経度の値を指定すると、リクエストは不正なリクエストとして拒否されます。
有効な URL を作成したまま、配列またはエンコードされたポリライン内で最大 512 個の座標を渡すことができます。複数の座標を渡すと、単一の座標のデータをリクエストする場合よりも、返されるデータの精度が低下することがあります。locations または path パラメータでポイントまたは座標が 512 を超えると、INVALID_REQUEST
レスポンスが返されます。
高度リクエストのレスポンス
高度サービスは、有効なリクエストごとにリクエスト URL 内で指定された形式で高度レスポンスを返します。
ElevationResponse
Field | Required | Type | Description |
---|---|---|---|
| required | Array<ElevationResult> | See ElevationResult for more information. |
| required | ElevationStatus | See ElevationStatus for more information. |
| optional | string |
When the service returns a status code other than |
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
Field | Required | Type | Description |
---|---|---|---|
| required | number | The elevation of the location in meters. |
| required | LatLngLiteral | 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. |
| optional | number | 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.
Field | Required | Type | Description |
---|---|---|---|
| required | number | Latitude in decimal degrees |
| required | number | 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
上の標高データをリクエストしています。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>