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

高度リクエスト

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"）として 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 個の座標を渡すことができます。ただし複数の座標を渡すと、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 の範囲の任意の値を取ることができます。無効な緯度または経度の値を指定すると、リクエストは不正なリクエストとして拒否されます。

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

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

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

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

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

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

ElevationResponse

フィールド 必須 タイプ 説明
required Array<ElevationResult> 詳細については、ElevationResult をご覧ください。
required ElevationStatus 詳細については、ElevationStatus をご覧ください。
省略可 文字列

サービスが 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

フィールド 必須 タイプ 説明
required 数値

その地点の高度（メートル単位）。
required LatLngLiteral

高度データを計算する地点の location 要素。なお、パス上のリクエストの場合は、location 要素のセットに、パス上のサンプリング地点が含まれています。

詳しくは、LatLngLiteral をご覧ください。

省略可 数値

高度の補間に使われたデータポイント間の最長距離をメートル単位で表す値。解像度が不明の場合は、このプロパティは存在しません。なお、複数の地点が渡された場合は、高度データがより粗く（解像度の値が大きくなる）なります。各地点の最も正確な高度値を取得するには、個別にクエリを行う必要があります。

LatLngLiteral

緯度と経度を 10 進数で表した特定の場所を表すオブジェクト。

フィールド 必須 タイプ 説明
required 数値

緯度（10 進法）
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>