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

高度のリクエスト

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 は、<ElevationResponse> ノード内にラップされた XML での出力を示します。

注: 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 の任意の値をとることができます。無効な緯度または経度の値を指定すると、リクエストは不正なリクエストとして拒否されます。

有効な URL を構築しながら、配列またはエンコードされたポリライン内で最大 512 個の座標を渡すことができます。ただし複数の座標を渡すと、1 つの座標に対するデータをリクエストしたときよりも、返されるデータの精度が落ち、低解像度になることがあるので注意してください。「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 の任意の値をとることができます。無効な緯度または経度の値を指定すると、リクエストは不正なリクエストとして拒否されます。

高度レスポンス

パイプ（'|'）文字で区切られた 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 で指定された形式で高度レスポンスを返します。

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 以外の場合、高度レスポンスオブジェクト内に error_message フィールドが追加されることがあります。このフィールドには、指定されたステータスコードの理由に関する詳細情報が含まれます。

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

ElevationResult

フィールド	必須	タイプ	説明
`elevation`	required	数値	その地点の高度（メートル単位）。
`location`	required	LatLngLiteral	高度データを計算する地点の位置のロケーション要素。なお、パス上のリクエストの場合は、位置要素のセットに、パス上のサンプリング地点が含まれています。詳細については、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`