高度リクエストと高度レスポンス

高度をリクエストする

Elevation API のリクエストは、URL 文字列として作成されます。この API は、地球上の地点の高度データを返します。地点データは、次のいずれかの方法で指定します。

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：XML で出力し、ノードでラップします。<ElevationResponse>

注: URL は有効になるように適切にエンコードする必要があります。また、すべてのウェブサービスで 16,384 文字に制限されています。URL を作成する際は、この制限に注意してください。ブラウザ、プロキシ、サーバーによって URL の文字数制限が異なる場合もあります。

API キーを使用するリクエストには HTTPS が必要です。

リクエストパラメータ

Elevation API へのリクエストでは、リクエストが個別の地点に対するものか、順序付けられたパスに対するものかに応じて、異なるパラメータが使用されます。個別の地点の場合、高度のリクエストは、リクエストで渡された特定の地点のデータを返します。パスの場合、高度のリクエストは、指定されたパスに沿ってデータをサンプリングします。

すべての URL の標準規則と同様に、パラメータはアンパサンド（&）文字を使用して区切ります。パラメータとその値のリストを以下に示します。

すべてのリクエスト

key -- （必須）アプリケーションの API キー。このキーは、割り当て管理の目的でアプリケーションを識別します。キーの取得方法をご覧ください。

位置リクエスト

locations（必須）は、標高データを返す地球上の地点を定義します。このパラメータには、カンマ区切りの {latitude,longitude} ペア（例: 「40.714728,-73.998672」）として 1 つの地点を指定するか、配列またはエンコードされたポリラインとして複数の緯度と経度のペアを渡します。このパラメータには 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の任意の値を取ることができます。無効な緯度または経度の値を指定すると、リクエストは不正なリクエストとして拒否されます。

配列またはエンコードされたポリライン内で最大 512 個の座標を渡すことができます。この場合でも、有効な URL が作成されます。ただし複数の座標を渡すと、1 つの座標に対するデータをリクエストしたときよりも、返されるデータの精度が落ち、低解像度になることがあるので注意してください。'locations' パラメータまたは 'path' パラメータで 512 個を超える地点または座標を指定すると、INVALID_REQUEST レスポンスが返されます。

パスを指定する

パス上でサンプリングした高度をリクエストするには、path パラメータと samples パラメータを使用します。これは、指定された間隔でパスに沿った高度データをリクエストします。locations パラメータを使用した位置リクエストと同様に、path パラメータは緯度と経度の値のセットを指定します。ただし、位置リクエストとは異なり、path で指定するのは順番に並んだ頂点のセットです。パス上の高度をリクエストすると、頂点の高度データが返される代わりに、指定されたsamples の数に基づいて、ルートの端から端まで（始点と終点を含めて）等間隔で並んだ地点においてサンプリングしたデータが返されます。

path パラメータには、次のいずれかの引数を指定できます。

パイプ文字（'|'）で区切られた、カンマ区切りの座標テキスト文字列の配列（2 つ以上）:path=40.714728,-73.998672|-34.397,150.644
エンコードポリラインアルゴリズムを使用したエンコードされた座標: Encoded Polyline Algorithm: path=enc:gfo}EtohhUxD@bAxJmGF

緯度と経度の座標文字列は、カンマ区切りのテキスト文字列内の数字を使用して定義されます。たとえば、「40.714728,-73.998672|-34.397, 150.644」は有効な path 値です。緯度と経度の値は、地球上の有効な地点に対応している必要があります。緯度は -90～90 の任意の値を取ることができ、経度は -180～180 の任意の値を取ることができます。無効な緯度または経度の値を指定すると、リクエストは不正なリクエストとして拒否されます。

高度リクエストのレスポンス

パイプ文字（'|'）で区切られた、カンマ区切りの座標テキスト文字列の配列（2 つ以上）:path=40.714728,-73.998672|-34.397,150.644
エンコードポリラインアルゴリズムを使用したエンコードされた座標: Encoded Polyline Algorithm: path=enc:gfo}EtohhUxD@bAxJmGF

緯度と経度の座標文字列は、カンマ区切りのテキスト文字列内の数字を使用して定義されます。たとえば、「40.714728,-73.998672|-34.397, 150.644」は有効な path 値です。緯度と経度の値は、地球上の有効な地点に対応している必要があります。緯度は -90～90の任意の値を取ることができ、経度は-180 ～-180の任意の値を取ることができます。無効な緯度または経度の値を指定すると、リクエストは不正なリクエストとして拒否されます。

高度リクエストのレスポンス

リクエストが有効な場合、高度サービスはリクエスト URL で指定された形式で高度レスポンスを返します。

ElevationResponse

フィールド	必須	タイプ	説明
`results`	required	Array<ElevationResult>	詳細については、 ElevationResult をご覧ください。
`status`	required	ElevationStatus	詳細については、 ElevationStatus をご覧ください。
`error_message`	省略可	文字列	サービスが `OK` 以外のステータスコードを返した場合、レスポンスオブジェクト内に `error_message` フィールドが追加されることがあります。このフィールドには、指定されたステータスコードの理由に関する詳細情報が含まれています。このフィールドは常に返されるわけではなく、その内容は変更される可能性があります。

ElevationStatus

サービスから返されるステータスコード。

OK: API リクエストが成功したことを示します。
DATA_NOT_AVAILABLE : 入力場所で利用できるデータがないことを示します。
INVALID_REQUEST: API リクエストの形式が正しくないことを示します。
OVER_DAILY_LIMIT : 次のいずれかを示します。
- API キーがないか、無効である。
- アカウントで課金が有効になっていない。
- ご自身で設定した使用量の上限を超えている。
- 設定したお支払い方法が無効になっている（クレジットカードの期限切れなど）。
OVER_QUERY_LIMIT: リクエストが割り当て量を超えたことを示します。
REQUEST_DENIED: API でリクエストを完了できなかったことを示します。
UNKNOWN_ERROR: 不明なエラーが発生したことを示します。

ステータスコードが OK 以外の場合、Elevation レスポンスオブジェクト内に error_message フィールドが追加されることがあります。このフィールドには、指定されたステータスコードの理由に関する詳細情報が含まれています。

レスポンスには、次の要素を含む results 配列が含まれます。

ElevationResult

フィールド	必須	タイプ	説明
`elevation`	required	数値	その地点の高度（メートル単位）。
`location`	required	LatLngLiteral	高度データを計算する地点の location 要素。なお、パス上のリクエストの場合は、location 要素のセットに、パス上のサンプリング地点が含まれています。詳細については、LatLngLiteral をご覧ください。
`resolution`	省略可	数値	高度の補間に使われたデータ地点間の最長距離（メートル単位）を示す値。解像度が不明の場合は、このプロパティは存在しません。なお、複数の地点が渡された場合は、高度データがより粗く（解像度の値が大きくなる）なります。各地点の最も正確な高度値を取得するには、個別にクエリを行う必要があります。

LatLngLiteral

緯度と経度を 10 進数で指定して、特定の地点を表すオブジェクト。

フィールド	必須	タイプ	説明
`lat`	required	数値	緯度（10 進数）
`lng`	required	数値	経度（10 進数）

位置の高度の例

次の例では、コロラド州デンバー（「マイルハイシティ」）の高度をリクエストします。

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>

高度リクエストと高度レスポンス

高度をリクエストする

リクエストパラメータ

すべてのリクエスト

位置リクエスト

パス上でサンプリングした高度をリクエストする

地点を指定する

パスを指定する

高度リクエストのレスポンス

高度リクエストのレスポンス

ElevationResponse

`results`

`status`

`error_message`

ElevationStatus

ElevationResult

`elevation`

`location`

`resolution`

LatLngLiteral

`lat`

`lng`

位置の高度の例

URL

cURL

JSON

XML

URL

cURL

JSON

XML

URL

cURL

JSON

XML

高度リクエストと高度レスポンス コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

高度をリクエストする

リクエスト パラメータ

すべてのリクエスト

位置リクエスト

パス上でサンプリングした高度をリクエストする

地点を指定する

パスを指定する

高度リクエストのレスポンス

高度リクエストのレスポンス

ElevationResponse

results

status

error_message

ElevationStatus

ElevationResult

elevation

location

resolution

LatLngLiteral

lat

lng

位置の高度の例

URL

cURL

JSON

XML

URL

cURL

JSON

XML

URL

cURL

JSON

XML

高度リクエストと高度レスポンス

リクエストパラメータ

`results`

`status`

`error_message`

`elevation`

`location`

`resolution`

`lat`

`lng`