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

高度のリクエスト

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: 出力が XML であることを示します（<ElevationResponse> ノード内にラップされます）。

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

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

リクエスト パラメータ

Elevation API へのリクエストでは、個別の場所に対するリクエストか、順序付けられたパスに対するリクエストかによって、異なるパラメータが使用されます。不連続の地点に対する標高のリクエストでは、リクエストで渡された特定の地点に関するデータが返されます。ルートに対する標高のリクエストでは、指定されたルートに沿ってサンプリングが行われます。

すべての URL の標準と同様に、パラメータはアンパサンド（&amp;）文字を使用して区切ります。各パラメータと有効な値のリストを次に示します。

すべてのリクエスト

  • 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
  • エンコード化ポリライン アルゴリズムを使用してエンコードされた 1 組の座標: 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

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

位置標高の例

次の例では、コロラド州デンバー（「マイル・ハイ・シティー」）の標高を 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>