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

高度をリクエストする

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

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

リクエスト パラメータ

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

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

すべてのリクエスト

  • key - （必須）アプリケーションの API キー。このキーでアプリケーションを識別し、割り当てを管理します。キーの取得方法を確認する。

位置リクエスト

  • locations（必須）は、高度データを返す地球上の場所を定義します。このパラメータは、カンマ区切りの {緯度,経度} のペア（例: 40.714728,-73.998672）として単一の場所を受け取るか、配列またはエンコードされたポリラインとして渡される複数の緯度と経度のペアを受け取ります。このパラメータのポイント上限は 512 です。詳しくは、後述のロケーションの指定をご覧ください。

サンプリングされたパスのリクエスト

  • path（必須）は、高度データを返す地球上のパスを定義します。このパラメータでは、2 つ以上の順序が指定された {緯度,経度} のペアのセットを定義し、地表に沿ったパスを定義します。このパラメータは、後述の 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 の任意の値を指定できます。無効な緯度または経度の値を指定すると、リクエストは不正なリクエストとして拒否されます。

有効な URL を構成しつつ、配列またはエンコードされたポリライン内で最大 512 個の座標を渡すことができます。複数の座標を渡すと、1 つの座標のデータをリクエストする場合よりも、返されるデータの精度が低下する可能性があります。「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 以外の場合、Elevation レスポンス オブジェクト内に追加の 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>